@adobe/acc-js-sdk 1.1.22 → 1.1.23

package/docs/_data/navigation.yml

@@ -87,6 +87,8 @@
       link: xtkJob.html
     - name: Handling timeouts
       link: timeouts.html
+    - name: Handling abort requests
+      link: abortRequest.html
     - name: HTTP Headers
       link: httpHeaders.html
     - name: The Transport Protocol

package/docs/abortRequest.html

@@ -0,0 +1,46 @@
+---
+layout: page
+title: Handling abort requests
+---
+
+<p>During development of an application, API requests are made for a variety of reasons, like user credential authentication, resource creation and fetching, etc. For multiple reasons though, sometimes aborting an API request might be required, which can also be done using Javascript. One such scenario where cancelling a request could be required would be the case when a user has navigated away from the page from which the request was made. Cancelling requests in appropriate scenarios could greatly enhance performance, reduce network traffic, and save crucial resources.</p>
+
+<h1>Aborting API requests in fetch</h1>
+
+<p>The fetch method in Javascript, which is used to make API requests, takes two arguments: the URL of the API endpoint and an object containing the request options.</p>
+
+<p>Canceling a fetch call works in the following step by step manner:</p>
+<ul>
+    <li>An <b>AbortController</b> instance is created</li>
+    <li>That instance has a <b>signal</b> property</li>
+    <li>The signal is passed as a fetch option for signal</li>
+    <li>AbortController's abort property is called to cancel all fetches that use that signal.</li>
+</ul>
+
+<h1>Aborting API requests in Axios</h1>
+
+<p>Axios is a JavaScript library that is used to make API requests. It has a very similar syntax to the fetch method. In the request options object, a signal property can also be set. On updating the aborted flag of the signal object to true, axios expression is notified, and the request is canceled.</p>
+
+<h1>Passing AbortSignal via PushDown Mechanism</h1>
+
+<p>SDK provides the support to pass the signal directly to transport layer via <b>PushDown Mechanism</b></p>
+
+<pre class="code">
+// Creating instance of abort controller    
+const instance = useRef<any>(new AbortController());
+
+// Lets say the new request is been made, so checking if the previously created instance is active
+// If yes, abort the previous request    
+if (instance.current) {
+    instance.current.abort();
+    instance.current = null;
+}
+
+// Reinitializing the instance 
+instance.current = new AbortController();
+
+// Pushing down the AbortSignal to the transport layer
+// signal.aborted is set to true if the previously made api request is currently active and that request is aborted 
+client.NLWS.pushDown({ signal: instance.current.signal }).xtkQueryDef.create(queryDef)
+</pre>
+

package/docs/assets/css/styles.css

@@ -99,6 +99,10 @@ nav ul {
   overflow: scroll
 }
 
+li li {
+  margin-left: 24px;
+}
+
 nav li {
   list-style: none;
 }

package/docs/changeLog.html

@@ -2,6 +2,16 @@
 layout: page
 title: Change Log
 ---
+<section class="changelog"><h1>Version 1.1.23</h1>
+  <h2>2023/03/02</h2>
+
+  <li>
+    Added support for abortable requests. See <a href="https://opensource.adobe.com/acc-js-sdk/abortRequest.html"> for more details.</a>
+  </li>
+  <li>
+    Added public function client.newSchema to create a new XtkSchema object from an XML document or element.
+  </li>
+</section>
 
 <section class="changelog"><h1>Version 1.1.22</h1>
   <h2>2023/01/19</h2>

package/docs/errors.html

@@ -6,26 +6,33 @@ title: Handling Errors
 
 <p>If an API call fails (SOAP fault or HTTP error), <b>CampaignException</b> object is thrown. This object contains the following attributes</p>
 
+<p></p>
+<ul>
 <li><b>message</b> a message describing the error</li>
-<li><b>statusCode</b> a HTTP status code. In case of a SOAP fault, the status code will be 500
-<li><b>errorCode</b> the Campaign error code if one is available (ex: XSV-350013)
+<li><b>statusCode</b> a HTTP status code. In case of a SOAP fault, the status code will be 500</li>
+<li><b>errorCode</b> the Campaign error code if one is available (ex: XSV-350013)</li>
 <li><b>methodCall</b> the SOAP call which caused the error. It will contain the following attributes
   <ul>
-    <li><b>type</b> the type of the API call ("SOAP" or "HTTP")
-    <li><b>urn</b> the SOAP call URN, i.e. the schema id. Will be empty for HTTP methods
-    <li><b>url</b> the HTTP URL
-    <li><b>methodName</b> the name of the SOAP method. For HTTP methods, the query path
-    <li><b>request</b> the raw SOAP request, as text. For HTTP requests, this is an option object containing details about the request
-    <li><b>response</b> the raw SOAP/HTTP response, as text
+    <li><b>type</b> the type of the API call ("SOAP" or "HTTP")</li>
+    <li><b>urn</b> the SOAP call URN, i.e. the schema id. Will be empty for HTTP methods</li>
+    <li><b>url</b> the HTTP URL</li>
+    <li><b>methodName</b> the name of the SOAP method. For HTTP methods, the query path</li>
+    <li><b>request</b> the raw SOAP request, as text. For HTTP requests, this is an option object containing details about the request</li>
+    <li><b>response</b> the raw SOAP/HTTP response, as text</li>
   </ul>
-<li><b>faultCode</b> for SOAP faults, the Campaign error code
-<li><b>faultString</b> the error message
-<li><b>detail</b> optional additional details about the error
+</li>
+<li><b>faultCode</b> for SOAP faults, the Campaign error code</li>
+<li><b>faultString</b> the error message</li>
+<li><b>detail</b> optional additional details about the error</li>
+</ul>
+<p></p>
 
 <p>
   In general all errors are mapped to a CampaignException and we try to keep the semantic of errors: for instance a call with an incorrect parameter will return an HTTP stauts of 400 even if it's not actually a, HTTP call. SDK specific errors will have an errorCode with the "SDK-######" format, using "SDK" as a prefix.
 </p>
 
+<p></p>
+
 <pre class="code">
 try {
   await client.logon();
@@ -45,3 +52,7 @@ try {
 <p>
   It's also noteworthy that all the data returned in a CampaignException is trimmed, i.e. session and security token values are hidden, so that the exception object can be safely logged.
 </p>
+
+<p class="info">
+  Note: The <a href="{{ site.baseurl }}/transport.html">transport</a> protocol returns errors of type HttpError which are wrapped into CampaignException objects.
+</p>

package/docs/transport.html

@@ -23,18 +23,20 @@ title: The Transport Protocol
 
 </ul>
 
-<p>The second parameter is an set of additional parameters that have been pushed down to the transport layer (see the <b>Pushdown</b> paragraph for more details). In particular, the <b>timeout</b> parameter should be honored by the transport layer.</p>
+<p>The second parameter is an set of additional parameters that have been pushed down to the transport layer (see the <b>Pushdown</b> paragraph for more details). In particular, the <b>timeout</b> and <b>AbortSignal</b> parameters should be honored by the transport layer.</p>
 
 <p>If the request is successful, a promise is returned with the result payload, as a string.</p>
 
-<p>If the request fails, the promise is rejected with an error object with class <b>HttpError</b>, a literal with the following attributes:</p>
+<p>If the request fails, the promise is rejected with an error object either having class <b>HttpError</b> or <b>AbortError</b></p>
+    
+<p>HttpError class has the following attributes:</p>
 <ul>
     <li><b>statusCode</b> is the HTTP status code, such as 404, 500, etc.</li>
     <li><b>statusText</b> is the HTTP status text coming with the error</li>
     <li><b>data</b> is the response data, if any</li>
 </ul>
 
-<p>For proper error handling by the ACC SDK, it's important that the actual class of returned objects is named <b>HttpError</b></p>
+<p>For proper error handling by the ACC SDK, it's important that the actual class of returned objects is named either <b>HttpError</b> or <b>AbortError</b></p>
 
 <p>The transport can be overriden by using the <b>client.setTransport</b> call and passing it a transport function, i.e. an async function which</p>
 

package/docs/xml2json.html

@@ -18,13 +18,13 @@ title: XML <=> JSON
 </p>
 
 <pre class="code">
-&amp;book title="A confederacy of dunces">
-  &amp;author>John Kennedy Toole&amp;/author>
-  &amp;chapter name="Chapter I" pages="20">
-  &amp;/chapter>
-  &amp;chapter name="Chapter II" pages="34">
-  &amp;/chapter>
-&amp;/book>  
+&lt;book title="A confederacy of dunces">
+  &lt;author>John Kennedy Toole&lt;/author>
+  &lt;chapter name="Chapter I" pages="20">
+  &lt;/chapter>
+  &lt;chapter name="Chapter II" pages="34">
+  &lt;/chapter>
+&lt;/book>  
 </pre>
 
 <p>
@@ -54,11 +54,11 @@ title: XML <=> JSON
 </p>
 
 <pre class="code">
-  &amp;book title="A confederacy of dunces">
-    &amp;author>John Kennedy Toole&amp;/author>
-    &amp;chapter name="Chapter I" pages="20">
-    &amp;/chapter>
-  &amp;/book>  
+  &lt;book title="A confederacy of dunces">
+    &lt;author>John Kennedy Toole&lt;/author>
+    &lt;chapter name="Chapter I" pages="20">
+    &lt;/chapter>
+  &lt;/book>  
 </pre>
 
 <p>

package/docs/xtkPackage.html

@@ -3,7 +3,9 @@ layout: page
 title: Packages
 ---
 
-<p>Test if a package is installed. Expects to be connected to an instance. Available since version 0.1.20</p>
+<h1>Test if a package is installed</h1>
+
+<p>Expects to be connected to an instance. Available since version 0.1.20</p>
 
 <pre class="code">
 var hasAmp = client.hasPackage("nms:amp");
@@ -14,3 +16,69 @@ var hasAmp = client.hasPackage("nms:amp");
 <pre class="code">
 var hasAmp = client.hasPackage("nms", "amp");
 </pre>
+
+
+<h1>Install a package</h1>
+
+<p>
+  A package can be installed with the <b>xtk:builder#installPackage</b> method. 
+  This method take a single argument which is the package definition, in XML or in JSON.
+</p>
+
+<p>
+  This is what a XML package looks like. Note the presence of the <b>&lt;pkgDesc&gt; root element</b>
+</p>
+<pre class="code">
+  
+  &lt;pkgDesc&gt;
+    &lt;package namespace="cus" name="sdk" buildNumber="*" buildVersion="*" 
+             label="Test package for ACC JS SDK" vendor="acc-js-sdk"&gt;
+      &lt;entities schema="xtk:option"&gt;
+        &lt;option name="AccJsSdk" dataType="6" stringValue="8.5.0"/&gt;
+      &lt;/entities&gt;
+    &lt;/package&gt;
+  &lt;/pkgDesc&gt;
+  
+</pre>
+
+<p>
+  In JSON, we have an objet containing a <b>package</b> object
+</p>
+<pre class="code">
+  { 
+    package: {
+      buildNumber: "*",
+      buildVersion: "*",
+      entities: {
+        schema:"nms:service",
+        service: {
+          label: "NewsletterTest",
+          name: "newsletterTest", 
+          folder: {
+            _operation: "none",
+            name: "nmsSetOfServices"
+          },
+          visitorFolder: {
+            _operation: "none",
+            name: "nmsVisitor"
+          }
+        }
+      }
+    }
+  }
+</pre>
+
+<p>
+  Installing package is a heavy operation which can involve database changes, and the call will often time out
+  if using the default settings. The best practice here is to keep short default timeouts, and explicitely increase
+  the timeout for the installPackage call.
+</p>
+
+<p>
+  This can be done using the <a href="{{ site.baseurl }}/pushDown.html">Push Down mechanism</a> as follows:
+</p>
+
+
+<pre class="code">
+  await NLWS.pushDown({ timeout: 5*60*1000 }).xtkBuilder.installPackage(jsonPackage);
+</pre>