@adobe/acc-js-sdk 1.0.2 → 1.0.6

package/.vscode/launch.json

@@ -4,7 +4,6 @@
     // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
-
         {
             "type": "node",
             "request": "launch",

package/CHANGELOG.md

@@ -3,7 +3,37 @@
 This is a node.js SDK for Campaign API. It exposes the Campaign API exactly like it is used inside Campaign using the NLWS notation.
 
 
-# Changelog
+# Changelog 
+
+## Version 1.0.6
+_2021/11/03_
+* New ofBearerToken authentication for IMS access token
+* Fix a small issue in the compile script which did not create the dist folder if it was missing
+* Fix an intermittent bug when running the SDK in the browser and when using local storage cache. The schema cache and method cache 
+  should contain XML representation of Campaign schemas and methods. Before it is put in local storage, data needs to be serialized
+  as text. This was only working of JavaScript objects, but DOM elements were not being serialied causing various errors when
+  using the cache later
+
+## Version 1.0.5
+_2021/10/09_
+* Fix an issue in the logon() function which was not always returning a promise. Some authentication methods such as SessionToken we returning synchronously. Made it so that logon always returns a promise. This should not be a breaking change as logon does not actually return a value
+* Refactor caches (Options cache, Schemas cache, and Methods cache) to use a generic cache class
+* Make sure options parameter of ConnectionParameters constructor is not modified
+* Added a persistent cache for schemas, methods, and options using the browser localStorage by default
+* Make sure X-Security-Token header is hidden as well as session token cookies
+* Added jshint configuration and fixed warnings reported by jshint
+* Fixed vulnerability in ansi-regex; upgrade jest-junit to version 13 to fix
+* Small jsdoc improvements
+
+## Version 1.0.4
+_2021/10/07_
+* Fix a bug which caused XML text and cdata elements to be skipped during SimpleJson transformation
+* Make sure passwords are not logged (replace with "***") when activating traces
+
+## Version 1.0.3
+_2021/10/06_
+* Added the `sdk.ip()` function to retreive the ouptbound IP to be whitelisted to access Campaign
+* New `ofSecurityToken` authentication method for the client-side SDK, which can be used to log on with a security token only. The session token will be passed automatically by the browser.
 
 ## Version 1.0.2
 _2021/09/17_

package/README.md

@@ -14,6 +14,11 @@ See the [Change log](./CHANGELOG.md) for more information about the different ve
 
 The API is fully asynchronous using promises and works as well on the server side than on the client side in the browser.
 
+Install
+```js
+npm install --save @adobe/acc-js-sdk
+```
+
 The SDK entrypoint is the `sdk` object from which everything else can be created.
 
 ```js
@@ -115,6 +120,13 @@ Attribute|Default|Description
 ---|---|---
 representation|"SimpleJson"| See below. Will determine if the SDK works with xml of json object. Default is JSON
 rememberMe|false| The Campaign `rememberMe` attribute which can be used to extend the lifetime of session tokens
+entityCacheTTL|300000| The TTL (in milliseconds) for the xtk entity cache
+methodCacheTTL|300000| The TTL (in milliseconds) for the xtk method cache
+optionCacheTTL|300000| The TTL (in milliseconds) for the xtk option cache
+traceAPICalls|false| Activates tracing of API calls or not
+transport|axios|Overrides the transport layer
+noStorage|false|De-activate using of local storage
+storage|localStorage|Overrides the local storage for caches
 
 ```js
 const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
@@ -133,6 +145,13 @@ const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
                                     "https://myInstance.campaign.adobe.com", 
                                     "admin", "==ims_service_token_here");
 ```
+## Login with IMS access token
+The SDK supports IMS access token of an IMS user with the `ofBearerToken` function. Pass it a bearer token.
+```js
+const connectionParameters = sdk.ConnectionParameters.ofBearerToken(
+                                    "https://myInstance.campaign.adobe.com", 
+                                    "ims_bearer_token");
+````
 
 ## Login with Session token
 
@@ -158,6 +177,35 @@ const connectionParameters = sdk.ConnectionParameters.ofAnonymousUser(url);
 const client = await sdk.init(connectionParameters);
 ```
 
+## Logon with Security token
+
+If you want to use the SDK client-side in a web page returned by Campaign, you cannot use the previous authentication functions because you do not know the user and password, and because you cannot read the session token cookie.
+
+For this scenario, the `ofSecurityToken` function can be used. Pass it a security token (usually available as document.__securitytoken), and the SDK will let the browser handle the session token (cookie) for you.
+
+```html
+    <script src="acc-sdk.js"></script>
+    <script>
+        (async () => {
+            try {
+                const sdk = document.accSDK;
+                var securityToken = "@UyAN...";
+	            const connectionParameters = sdk.ConnectionParameters.ofSecurityToken(url, securityToken);
+                const client = await sdk.init(connectionParameters);
+                await client.logon();
+                const option = await client.getOption("XtkDatabaseId");
+                console.log(option);
+            } catch(ex) {
+                console.error(ex);
+            }
+        })();
+    </script>
+    </body>
+</html>
+```
+
+Note: if the HTML page is served by the Campaign server (which is normally the case in this situation), you can pass an empty url to the `ofSecurityToken` API call.
+
 
 ## LogOn / LogOff
 
@@ -171,6 +219,24 @@ await client.logon();
 await client.logoff();
 ```
 
+## IP Whitelisting
+
+Campaign includes an IP whitelisting component which prevents connections from unauthorized IP addresses. This is a common source of authentication errors. 
+
+A node application using the SDK must be whitelisted to be able to access Campaign. The SDK `ip` function is a helper function that can help you find the IP or IPs which need to be whitelisted.
+
+This API is only meant for troubleshooting purposes and uses the `https://api.db-ip.com/v2/free/self` service.
+
+```js
+const ip = await sdk.ip();
+```
+
+Will return something like
+
+```json
+{ "ipAddress":"AAA.BBB.CCC.DDD","continentCode":"EU","continentName":"Europe","countryCode":"FR","countryName":"France","stateProv":"Centre-Val de Loire","city":"Bourges" }
+```
+
 ## Calling static SOAP methods
 
 The NLWS object allows to dynamically perform SOAP calls on the targetted Campaign instance.
@@ -513,7 +579,7 @@ It's also noteworthy that all the data returned in a CampaignException is trimme
 
 ## Caches
 
-The following caches are manage by the SDK
+The following caches are managed by the SDK and active by default. They are in-memory caches.
 
 * Options cache. Stores typed option values, by option name.
 * Entity cache. Caches schemas and other entities
@@ -531,6 +597,21 @@ or
 client.clearAllCaches();
 ```
 
+Caches have a TTL of 5 minutes by default. The TTL can be changed at connection time using connection options `entityCacheTTL`, `methodCacheTTL`, and `optionCacheTTL`.
+
+Caches can be de-activated by setting a TTL of -1 which will have the effect of making all cached data always invalid.
+
+
+
+## Persistent caches
+In addition to memory caches, it is possible to use persistent caches as well. This was introduced in version 1.0.5 and is active by default as well when using the SDK in a browser. The browser local storage is used (if allowed).
+
+Cached data is stored in local storage with keys prefixed with  `acc.js.sdk.{{version}}.{{server}}.cache.` where `version` is the SDK version and `server` is the Campaign server name. This means that the cached data is lost when upgrading the SDK.
+
+It's possible to disable persistent caches using the `noStorage` connection option.
+
+It is also possible to setup one's own persistent cache, by passing a `storage` object as a connection option. This object should implement 3 methods: `getItem`, `setItem`, and `removeItem` (synchronous)
+
 
 ## Passwords
 
@@ -1365,9 +1446,20 @@ If you need to access entity attributes (or child elements) in a generic way, yo
 
 To build this project, you need node and npm
 
-````
+```sh
 npm install
-````
+```
+
+## Check and resolve any security issues
+```sh
+npm audit
+npm audit fix --force
+```
+
+## Check if there are any code warnings
+```sh
+node_modules/jshint/bin/jshint src/
+```
 
 ## Run tests
 ```sh
@@ -1377,6 +1469,7 @@ npm run unit-tests
 ## Build JavaScript documentation
 ```sh
 npm run jsdoc
+open ./docs/jsdoc/index.html
 ```
 
 The HTML doc will be generated in the docs/ folder

package/compile.js

@@ -31,6 +31,7 @@ var resources = [
     { name: "./transport.js" },
     { name: "./xtkCaster.js" },
     { name: "./domUtil.js" },
+    { name: "./cache.js" },
     { name: "./entityAccessor.js" },
     { name: "./xtkEntityCache.js" },
     { name: "./methodCache.js" },
@@ -44,6 +45,7 @@ var resources = [
 
 
 const outFileName = "./dist/bundle.js";
+if (!fs.existsSync("./dist")) fs.mkdirSync("./dist"); 
 const rootPath = "./src";