@adobe/acc-js-sdk 1.0.5 → 1.0.8

package/src/cache.js

@@ -0,0 +1,275 @@
+/*
+Copyright 2020 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+(function() {
+"use strict";    
+  
+
+/**********************************************************************************
+ * 
+ * Cache utilities
+ * 
+ *********************************************************************************/
+
+/**
+ * @namespace Utils
+ */
+
+
+/**********************************************************************************
+ * 
+ * A simple cache for XtkEntities, options, etc.
+ * 
+ *********************************************************************************/
+
+/**
+ * @private
+ * @class
+ * @constructor
+ * @memberof Utils
+ */
+class SafeStorage {
+
+  /**
+   * A wrapper to the Storage interface (LocalStorage, etc.) which is "safe", i.e.
+   * 
+   * - it will never throw / support local stroage to be undefined or not accessible
+   * - Handle the notion of "root key", i.e. prefix 
+   * - Set/get values as JSON only and not as strings
+   * - Silently caches all exceptions
+   * - Automatically remove from storage cached values which are not valid, expired, or cannot be parsed
+   * 
+   * SafeStorage objects are created automatically by Caches
+   * 
+   * @param {Storage} delegate an optional delegate options, confomring to the Storage interface (getItem, setItem, removeItem)
+   * @param {string} rootKey an optional prefix which will be prepend to all keys
+   * @param {function} serDeser serializarion & deserialization function. First parameter is the object or value to serialize
+   *                            or deserialize, and second parameter is true for serialization or false for deserialization
+   */
+  constructor(delegate, rootKey, serDeser) {
+    if (!serDeser)
+      serDeser = (item, serDeser) => {
+        if (serDeser) { 
+          if (!item) throw Error(`Cannot serialize falsy cached item`);
+          if (typeof item !== "object") throw Error(`Cannot serialize non-object`);
+          return JSON.stringify(item); 
+        }
+        else { 
+          if (!item) throw Error(`Cannot deserialize falsy cached item`);
+          return JSON.parse(item); 
+        }
+    };
+    this._delegate = delegate;
+    this._rootKey = rootKey ? `${rootKey}$` : "";
+    this._serDeser = serDeser;
+  }
+
+  /**
+   * Get an item from storage
+   * @param {string} key the item key (relative to the root key)
+   * @returns {Utils.CachedObject} the cached object, or undefined if not found. 
+   *                               The storage serDeser fucntion will be used to deserialize the cached value
+   */
+  getItem(key) {
+    if (!this._delegate || this._rootKey === undefined || this._rootKey === null)
+      return;
+    const itemKey = `${this._rootKey}${key}`;
+    const raw = this._delegate.getItem(itemKey);
+    if (!raw)
+      return undefined;
+    try {
+      return this._serDeser(raw, false);
+    } catch(ex) {
+      this.removeItem(key);
+    }
+  }
+
+  /**
+   * Put an item into storage
+   * @param {string} key the item key (relative to the root key)
+   * @param {Utils.CachedObject} json the object to cache
+   *                               The storage serDeser fucntion will be used to serialize the cached value
+   */
+   setItem(key, json) {
+    if (!this._delegate || this._rootKey === undefined || this._rootKey === null)
+      return;
+    try {
+      //if (json && typeof json === "object") {
+      const raw = this._serDeser(json, true);
+      this._delegate.setItem(`${this._rootKey}${key}`, raw);
+      return;
+    } catch(ex) { /* Ignore errors in safe class */
+    }
+    this.removeItem(key);
+  }
+
+  /**
+   * Removes an item from the storage
+   * @param {string} key the item key (relative to the root key)
+   */
+  removeItem(key) {
+    if (!this._delegate || this._rootKey === undefined || this._rootKey === null)
+      return;
+    try {
+      this._delegate.removeItem(`${this._rootKey}${key}`);
+    } catch(ex) { /* Ignore errors in safe class */
+    }
+  }
+}
+
+/**
+ * @private
+ * @class
+ * @constructor
+ * @memberof Utils
+ */
+class CachedObject {
+
+  /**
+   * An object in the cache, i.e. a wrapped to a cached value and additional metadata to manage the cache.
+   * Do not create such objects directly, they are 100% managed by the Cache object
+   * 
+   * @param {*} value the cached value
+   * @param {number} cachedAt the timestamp at which the value was cached
+   * @param {number} expiresAt the timestamp at which the cached value expires
+   */
+  constructor(value, cachedAt, expiresAt) {
+      this.value = value;
+      this.cachedAt = cachedAt;
+      this.expiresAt = expiresAt;
+  }
+}
+
+/** 
+ * @private
+ * @class
+ * @constructor
+ * @memberof Utils
+ */
+class Cache {
+
+  /**
+   * A general purpose in-memory cache with TTL. In addition to caching in memory, the cache has the ability to delegate the caching
+   * to a persistent cache, such as the browser localStorage. The interface is 100% synchronous.
+   * 
+   * By default, caches take a single parameter for the key. It is possible however to use a more complex scenario by setting a makeKeyFn.
+   * When set, such a function will take 1 or more arguments and will be responsible to create a primitive key (a string) from the arguments.
+   * The cache public APIs : get and put therefore can take a variable number of key arguments, which will be combined into the actual primitive key.
+   * 
+   * @param {Storage} storage is an optional Storage object, such as localStorage or sessionStorage. This object will be wrapped into a SafeStorage object to ensure access is safe and will not throw any exceptions
+   * @param {string} rootKey is an optional root key to use for the storage object
+   * @param {number} ttl is the TTL for objects in ms. Defaults to 5 mins
+   * @param {function} makeKeyFn is an optional function which will generate a key for objects in the cache. It's passed the arguments of the cache 'get' function
+   * @param {function} serDeser serializarion & deserialization function. First parameter is the object or value to serialize
+   *                            or deserialize, and second parameter is true for serialization or false for deserialization
+   */
+  constructor(storage, rootKey, ttl, makeKeyFn, serDeser) {
+      this._storage = new SafeStorage(storage, rootKey, serDeser);
+      this._ttl = ttl || 1000*300;
+      this._makeKeyFn = makeKeyFn || ((x) => x);
+      this._cache = {};
+      // timestamp at which the cache was last cleared
+      this._lastCleared = this._loadLastCleared();
+  }
+
+  // Load timestamp at which the cache was last cleared
+  _loadLastCleared() {
+    const json = this._storage.getItem("lastCleared");
+    return json ? json.timestamp : undefined;
+  }
+
+  _saveLastCleared() {
+    const now = Date.now();
+    this._lastCleared = now;
+    this._storage.setItem("lastCleared", { timestamp: now});
+  }
+
+  // Load from local storage
+  _load(key) {
+    const json = this._storage.getItem(key);
+    if (!json || !json.cachedAt || json.cachedAt <= this._lastCleared) {
+      this._storage.removeItem(key);
+      return;
+    }
+    return json;
+  }
+
+  // Save to local storage
+  _save(key, cached) {
+    this._storage.setItem(key, cached);
+  }
+
+  // Remove from local storage
+  _remove(key) {
+    this._storage.removeItem(key);
+  }
+
+  _getIfActive(key) {
+    // In memory cache?
+    var cached = this._cache[key];
+    // Local storage ?
+    if (!cached) {
+      cached = this._load(key);
+      this._cache[key] = cached;
+    }
+    if (!cached) 
+      return undefined;
+    if (cached.expiresAt <= Date.now()) {
+      delete this._cache[key];
+      this._remove(key);
+      return undefined;
+    }
+    return cached.value;
+  }
+
+  /**
+   * Get a value from the cache
+   * @param {*} key the key or keys of the value to retreive
+   * @returns {*} the cached value, or undefined if not found
+   */
+  get() {
+      const key = this._makeKeyFn.apply(this, arguments);
+      const cached = this._getIfActive(key);
+      return cached;
+  }
+
+  /**
+   * Put a value from the cache
+   * @param {*} key the key or keys of the value to retreive
+   * @param {*} value the value to cache
+   * @returns {CachedObject} a cached object containing the cached value
+   */
+   put() {
+      const value = arguments[arguments.length -1];
+      const key = this._makeKeyFn.apply(this, arguments);
+      const now = Date.now();
+      const expiresAt = now + this._ttl;
+      const cached = new CachedObject(value, now, expiresAt);
+      this._cache[key] = cached;
+      this._save(key, cached);
+      return cached;
+  }
+  
+  /**
+   * Removes everything from the cache. It does not directly removes data from persistent storage if there is, but it marks the cache
+   * as cleared so that subsequent get operation will not actually return any data cached in persistent storage
+   */
+  clear() {
+      this._cache = {};
+      this._saveLastCleared();
+  }
+}
+
+// Public expots
+exports.SafeStorage = SafeStorage;
+exports.Cache = Cache;
+
+})();

package/src/campaign.js

@@ -37,6 +37,7 @@ const { Util } = require("./util.js");
   static SOAP_UNKNOWN_METHOD(schema, method, details)     { return new CampaignException(undefined, 400, 16384, `SDK-000009 Unknown method '${method}' of schema '${schema}'`, details); }
   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.`); }
   
 
   /**
@@ -223,6 +224,9 @@ function makeCampaignException(call, err) {
       faultString = err.data;
       details = undefined;
     }
+    // Session expiration case must return a 401
+    if (err.data && err.data.indexOf(`XSV-350008`) != -1)
+        return CampaignException.SESSION_EXPIRED();
     return new CampaignException(call, err.statusCode, "", faultString, details, err);
   }
 

package/src/client.js

@@ -178,11 +178,15 @@ class Credentials {
      */
     constructor(type, sessionToken, securityToken) {
         if (type != "UserPassword" && type != "ImsServiceToken" && type != "SessionToken" && 
-            type != "AnonymousUser" && type != "SecurityToken")
+            type != "AnonymousUser" && type != "SecurityToken" && type != "BearerToken")
             throw CampaignException.INVALID_CREDENTIALS_TYPE(type);
         this._type = type;
         this._sessionToken = sessionToken || "";
         this._securityToken = securityToken || "";
+        if (type == "BearerToken") {
+            this._bearerToken = sessionToken || "";
+            this._sessionToken = "";
+        }
     }
 
     /**
@@ -221,16 +225,16 @@ class Credentials {
 
 /**
  * @typedef {Object} ConnectionOptions
- * @property {string} representation - the representation to use, i.e. "SimpleJson" (the default), "BadgerFish", or "xml"
- * @property {boolean} rememberMe - The Campaign `rememberMe` attribute which can be used to extend the lifetime of session tokens
- * @property {number} entityCacheTTL - The TTL (in milliseconds) after which cached XTK entities expire. Defaults to 5 minutes
- * @property {number} methodCacheTTL - The TTL (in milliseconds) after which cached XTK methods expire. Defaults to 5 minutes
- * @property {number} optionCacheTTL - The TTL (in milliseconds) after which cached XTK options expire. Defaults to 5 minutes
- * @property {boolean} traceAPICalls - Activates the tracing of all API calls
- * @property {Utils.Transport} transport - Overrides the transport (i.e. HTTP layer)
- * @property {boolean} noStorage - De-activate using of local storage. By default, and in addition to in-memory cache, entities, methods, and options are also persisted in local storage if there is one.
- * @property {Storage} storage - Overrides the storage interface (i.e. LocalStorage)
- * @memberOf Campaign
+    * @property {string} representation - the representation to use, i.e. "SimpleJson" (the default), "BadgerFish", or "xml"
+    * @property {boolean} rememberMe - The Campaign `rememberMe` attribute which can be used to extend the lifetime of session tokens
+    * @property {number} entityCacheTTL - The TTL (in milliseconds) after which cached XTK entities expire. Defaults to 5 minutes
+    * @property {number} methodCacheTTL - The TTL (in milliseconds) after which cached XTK methods expire. Defaults to 5 minutes
+    * @property {number} optionCacheTTL - The TTL (in milliseconds) after which cached XTK options expire. Defaults to 5 minutes
+    * @property {boolean} traceAPICalls - Activates the tracing of all API calls
+    * @property {Utils.Transport} transport - Overrides the transport (i.e. HTTP layer)
+    * @property {boolean} noStorage - De-activate using of local storage. By default, and in addition to in-memory cache, entities, methods, and options are also persisted in local storage if there is one.
+    * @property {Storage} storage - Overrides the storage interface (i.e. LocalStorage)
+    * @memberOf Campaign
  */
  
 
@@ -292,6 +296,7 @@ class ConnectionParameters {
             }    
         }
         this._options._storage = storage;
+        this._options.refreshClient = options.refreshClient;
     }
 
     /**
@@ -308,6 +313,18 @@ class ConnectionParameters {
         return new ConnectionParameters(endpoint, credentials, options);
     }
 
+    /**
+     * Creates connection parameters for a Campaign instance from bearer token
+     * 
+     * @param {string} endpoint The campaign endpoint (URL)
+     * @param {string} bearerToken IMS bearer token
+     * @param {*} options connection options
+     * @returns {ConnectionParameters} a ConnectionParameters object which can be used to create a Client
+     */
+    static ofBearerToken(endpoint, bearerToken, options) {
+        const credentials = new Credentials("BearerToken", bearerToken);
+        return new ConnectionParameters(endpoint, credentials, options);
+    }
     /**
      * Creates connection parameters for a Campaign instance, using an IMS service token and a user name (the user to impersonate)
      * 
@@ -462,6 +479,7 @@ class Client {
         this._transport = connectionParameters._options.transport;
         this._traceAPICalls = connectionParameters._options.traceAPICalls;
         this._observers = [];
+        this._refreshClient = connectionParameters._options.refreshClient;
 
         // expose utilities
 
@@ -624,6 +642,17 @@ class Client {
         if (credentialsType == "AnonymousUser")
             return true;
 
+        // When using bearer token authentication we are considered logged only after
+        // the bearer token has been converted into session token and security token
+        // by method xtk:session#BearerTokenLogon
+        if( credentialsType == "BearerToken")
+            return this._sessionToken != undefined &&
+                   this._sessionToken != null &&
+                   this._sessionToken != "" &&
+                   this._securityToken != undefined &&
+                   this._securityToken != null &&
+                   this._securityToken != "";
+
         // with session token authentication, we do not expect a security token
         // with security token authentication, we do not expect a session token
         const needsSecurityToken = credentialsType != "SessionToken";
@@ -649,6 +678,38 @@ class Client {
         return soapCall;
     }
 
+    /**
+     * Retry a a SOAP call
+     *
+     * @private
+     * @return {SOAP.SoapMethodCall} a SoapMethodCall to retry
+     * parameters should be set
+     */
+    async _retrySoapCall(soapCall) {
+        soapCall.retry = false;
+        var newClient = await this._refreshClient(this); 
+        soapCall.finalize(newClient._soapEndPoint(), newClient);
+        if (this._traceAPICalls) {
+            const safeCallData = Util.trim(soapCall.request.data);
+            console.log(`RETRY SOAP//request ${safeCallData}`);
+        }
+        await soapCall.execute();
+        if (this._traceAPICalls) {
+            const safeCallResponse = Util.trim(soapCall.response);
+            console.log(`SOAP//response ${safeCallResponse}`);
+        }
+        return;
+    }
+
+    /**
+     *  SOAP Endpoint
+     *
+     * @private
+     * @return {string} soap call End point
+     */
+    _soapEndPoint() {
+        return this._connectionParameters._endpoint + "/nl/jsp/soaprouter.jsp";
+    }
     /**
      * After a SOAP method call has been prepared with '_prepareSoapCall', and parameters have been added,
      * this function actually executes the SOAP call
@@ -660,8 +721,7 @@ class Client {
         const that = this;
         if (soapCall.requiresLogon() && !that.isLogged())
             throw CampaignException.NOT_LOGGED_IN(soapCall, `Cannot execute SOAP call ${soapCall.urn}#${soapCall.methodName}: you are not logged in. Use the Logon function first`);
-        var soapEndpoint = that._connectionParameters._endpoint + "/nl/jsp/soaprouter.jsp";
-        soapCall.finalize(soapEndpoint);
+        soapCall.finalize(this._soapEndPoint());
         
         const safeCallData = Util.trim(soapCall.request.data);
         if (that._traceAPICalls)
@@ -680,7 +740,12 @@ class Client {
                 if (that._traceAPICalls)
                     console.log(`SOAP//failure ${ex.toString()}`);
                 that._notifyObservers((observer) => observer.onSOAPCallFailure && observer.onSOAPCallFailure(soapCall, ex) );
-                return Promise.reject(ex);
+                // Call session expiration callback in case of 401
+                if (ex.statusCode == 401 && that._refreshClient && soapCall.retry) {
+                    return this._retrySoapCall(soapCall);
+                }
+                else
+                    return Promise.reject(ex);
             });
     }
 
@@ -708,28 +773,34 @@ 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;
             that.application = new Application(that);
             return Promise.resolve();
         }
-        else if (credentials._type == "UserPassword") {
-            const user = credentials._getUser();
-            const password = credentials._getPassword();
-
-            const soapCall = this._prepareSoapCall("xtk:session", "Logon");
-            soapCall.writeString("login", user);
-            soapCall.writeString("password", password);
-            var parameters = null;
-            if (this._connectionParameters._options.rememberMe) {
-                parameters = soapCall.createElement("parameters");
-                parameters.setAttribute("rememberMe", "true");
+        else if (credentials._type == "UserPassword" || credentials._type == "BearerToken") {
+            const soapCall = that._prepareSoapCall("xtk:session", credentials._type === "UserPassword" ? "Logon" : "BearerTokenLogon");
+            // No retry for logon SOAP methods
+            soapCall.retry = false;
+            if (credentials._type == "UserPassword") {
+                const user = credentials._getUser();
+                const password = credentials._getPassword();
+                soapCall.writeString("login", user);
+                soapCall.writeString("password", password);
+                var parameters = null;
+                if (this._connectionParameters._options.rememberMe) {
+                    parameters = soapCall.createElement("parameters");
+                    parameters.setAttribute("rememberMe", "true");
+                }
+                soapCall.writeElement("parameters", parameters);
             }
-            soapCall.writeElement("parameters", parameters);
-            
+            else {
+                const bearerToken = credentials._bearerToken;
+                soapCall.writeString("bearerToken", bearerToken);
+            } 
             return this._makeSoapCall(soapCall).then(function() {
                 const sessionToken = soapCall.getNextString();
                 
@@ -782,7 +853,6 @@ class Client {
     logoff() {
         var that = this;
         if (!that.isLogged()) return;
-        
         const credentials = this._connectionParameters._credentials;
         if (credentials._type != "SessionToken" && credentials._type != "AnonymousUser") {
             var soapCall = that._prepareSoapCall("xtk:session", "Logoff");
@@ -1032,6 +1102,14 @@ class Client {
         var urn = that._methodCache.getSoapUrn(schemaId, methodName);
         var soapCall = that._prepareSoapCall(urn, methodName);
 
+        // 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
+        let isfunc = parameters && typeof parameters === "function";
+        if (!isfunc && parameters && parameters.length >= 1 && typeof parameters[0] === "function")
+            isfunc = true;
+        if (isfunc)
+            parameters = parameters[0](method, callContext);
+
         const isStatic = DomUtil.getAttributeAsBoolean(method, "static");
         var object = callContext.object;
         if (!isStatic) {

package/src/domUtil.js

@@ -19,7 +19,7 @@ var JSDOM;
 
 /* istanbul ignore else */
 if (!Util.isBrowser()) {
-  JSDOM = require("jsdom").JSDOM;
+    JSDOM = require("jsdom").JSDOM;
 }
 
 /**********************************************************************************
@@ -40,7 +40,7 @@ else {
         return new XMLSerializer().serializeToString(dom);
     };
   };
-
+  
   JSDOM = jsdom;
 }
 
@@ -562,7 +562,10 @@ class XPathElement {
 class XPath {
 
     constructor(path) {
-        this._path = (path || "").trim();
+        path = (path || "").trim();
+        if (path && path.startsWith("[") && path.endsWith("]"))
+            path = path.substring(1, path.length - 1).trim();
+        this._path = path;
     }
 
     /**

package/src/entityAccessor.js

@@ -69,7 +69,7 @@ class EntityAccessor {
      */
     static getAttributeAsString(entity, name) {
         if (entity.documentElement) entity = entity.documentElement;
-        if (entity.insertAdjacentElement)
+        if (entity.nodeType && entity.tagName)
             return DomUtil.getAttributeAsString(entity, name);
         else if (entity instanceof BadgerFishObject)
             return XtkCaster.asString(entity[`@${name}`]);
@@ -95,7 +95,7 @@ class EntityAccessor {
      */
     static getAttributeAsLong(entity, name) {
         if (entity.documentElement) entity = entity.documentElement;
-        if (entity.insertAdjacentElement)
+        if (entity.nodeType && entity.tagName)
             return DomUtil.getAttributeAsLong(entity, name);
         else if (entity instanceof BadgerFishObject)
             return XtkCaster.asLong(entity[`@${name}`]);
@@ -121,7 +121,7 @@ class EntityAccessor {
      */
     static getAttributeAsBoolean(entity, name) {
         if (entity.documentElement) entity = entity.documentElement;
-        if (entity.insertAdjacentElement)
+        if (entity.nodeType && entity.tagName)
             return DomUtil.getAttributeAsBoolean(entity, name);
         else if (entity instanceof BadgerFishObject)
             return XtkCaster.asBoolean(entity[`@${name}`]);
@@ -148,7 +148,7 @@ class EntityAccessor {
      */
     static getChildElements(entity, tagName) {
         if (entity.documentElement) entity = entity.documentElement;
-        if (entity.insertAdjacentElement) {
+        if (entity.nodeType && entity.tagName) {
             const elements = [];
             var child = DomUtil.getFirstChildElement(entity);
             while (child) {
@@ -184,7 +184,7 @@ class EntityAccessor {
      */
     static getElement(entity, tagName) {
         if (entity.documentElement) entity = entity.documentElement;
-        if (entity.insertAdjacentElement) {
+        if (entity.nodeType && entity.tagName) {
             var child = DomUtil.getFirstChildElement(entity);
             while (child) {
                 if (tagName == child.tagName)

package/src/index.js

@@ -23,6 +23,7 @@ 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');
 
 /**
  * Get/Set the transport function (defaults to Axios). This function is used for testing / mocking the transport layer.
@@ -127,8 +128,7 @@ class SDK {
      * @example
      * expect(sdk.escapeXtk`@name=${"Rock 'n' Roll"}`).toBe("@name='Rock \\'n\\' Roll'");
      */
-    escapeXtk(p1, ...p2)
-    {
+    escapeXtk(p1, ...p2) {
         // first syntax: only one parameter which is a string => returns the escaped string.
         // that's how the Campaign function in common.js behaves
         if (p1 === undefined || p1 === null)
@@ -147,9 +147,65 @@ class SDK {
         }
         return str;
     }
+
+    /**
+     * Escapes a string of characters so that in can be used in a SQL like statement.
+     * @param {string | any} text the text to escape. If not a string, it will be casted to a xtk string first
+     * @param {boolean?} escapeXtkParams indicates that the escape text contains Xtk parameters (using $ character)
+     * @returns the escaped string
+     */
+    escapeForLike(text, escapeXtkParams) {
+        text = XtkCaster.asString(text);
+        if (!text) return "";    
+        text = text.replace(/\\/g, "\\\\")
+                    .replace(/'/g,  "\\'")
+                    .replace(/%/g,  "\\%")
+                    .replace(/_/g,  "\\_");
+        if (escapeXtkParams)
+            text = text.replace(/\$/g, "' + Char('36') + '");
+      return text;
+    }
+
+    /**
+     * Expands an xpath, i.e. enclose it with [..] brackets if necessary
+     * @param {string} xpath the xpath
+     * @returns {string} the expanded xpath
+     */
+    expandXPath(xpath) {
+        if (!xpath) return xpath;
+        if (xpath.startsWith("[") && xpath.endsWith("]"))
+            return xpath;
+        if (xpath.indexOf('/') === -1 && xpath.indexOf('-') === -1 && xpath.indexOf(':') === -1)
+            return xpath;
+        return `[${xpath}]`;
+    }
+
+    unexpandXPath(xpath) {
+        if (!xpath) return xpath;
+        if (xpath.startsWith("[") && xpath.endsWith("]"))
+            return xpath.substring(1, xpath.length - 1);
+        return xpath;
+    }
+
+    /**
+     * Convert a javascript value into an xtk constant with proper quoting
+     * @param {any} value the value to convert
+     * @param {string} type the xtk type
+     * @returns 
+     */
+    xtkConstText(value, type) {
+        if (!type || type === 'string' || type === 'memo') {
+            return sdk.escapeXtk(XtkCaster.asString(value));
+        }
+        const constText = XtkCaster.asString(XtkCaster.as(value, type));
+        if (XtkCaster.isTimeType(type))
+            return `#${constText}#`;
+        return constText;
+    }
 }
 
 const sdk = new SDK();
+sdk.TestUtil = TestUtil;
 sdk.XtkCaster = XtkCaster;
 sdk.Credentials = Credentials;
 sdk.DomUtil = DomUtil;