@adobe/acc-js-sdk 1.0.6 → 1.0.9

package/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,70 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ master ]
+  schedule:
+    - cron: '34 13 * * 4'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'javascript' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://git.io/codeql-language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ This is a node.js SDK for Campaign API. It exposes the Campaign API exactly like
 
 # Changelog 
 
+## Version 1.0.9
+_2022/03/02_
+
+* Ability to invoke SOAP calls dynamically with parameters computed at invocation time by a delegate function
+* Fixed bug in XPath constructor which now supports expanded paths, i.e. xpaths such as `[@recipient-id]`.
+* EntityAccessor: change the heuristic to detect XML types: use "nodeType" and "tagName" functions instead of "insertAdjacentElement" (which was not always working in the context of a React application)
+* Add new escaping functions: `escapeForLike`, `expandXPath`, `unexpandXPath`, `xtkConstText`
+* New XtkCaster methods: `asDatetime` (alias to `asTimestamp`), `isStringType`, and `isNumericType`
+* Metadata API (application.getSchema)
+  * keys have a `isInternal` internal attribute which was mistakenly using the "string" type. It's now correctly using the boolean type.
+  * Added missing attributes on the XtkSchema: md5
+  * Added missing attributes on the XtkSchemaNode objects: dataPolicy, editType folderModel, enumerationImage, size, userEnumeration, hasUserEnumeration, isCollection, 
+    isAdvanced, isAnyType, isLink, hasEnumeration, hasSQLTable, SQLName, SQLTable, isMappedAsXML, isTemporaryTable, isElementOnly, isDefaultOnDuplicate, isExternalJoin, 
+    isMemo, isMemoData, isBlob, isCDATA, isNotNull, isRequired, isSQL, PKSequence, revLink, isCalculated, expr, isAutoIncrement, isAutoPK,  isAutoUUID, isAutoStg, packageStatusString, and packageStatus
+  * Attribute type defaults to string if not set
+  * Removed userDescription attribut from schema nodes (only available at the schema level)
+  * Changed the toString function to use 4 spaces instead of 3 for indentation and display node label and internal name
+  * When label or description is missing from schema nodes or from enumerations, they default to the name value
+  * application.getSchema now uses a in-memory cache
+
+
+## Version 1.0.7
+_2022/01/24_
+* Added a hook `refreshClient` on connection parameters. This is a callback called when an authentication token expires. It can be used to implement reconnection logic
+* New attributes on the schema API (application.getSchema)
+  * The `enum` attribute of a schema node returns the corresponding enum attribute, i.e. the enumeration name
+  * The `target` attribute of a schema node (of type link) returns the target (schema id) of the link
+  * The `integrity` attribute of a schema node (of type link) returns the link integrity ("define", "own", etc.)
+* Added a github workflow for code analysis (CodeQL) to detect more potential issues before release
+* Upgrade dependencies to fix some vulnerabilities
+* Add new conversion functions in XtkCaster to support for int, timespan, uuid, html and blob
+
 ## Version 1.0.6
 _2021/11/03_
 * New ofBearerToken authentication for IMS access token

package/README.md

@@ -3,6 +3,7 @@
 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.
 
 
+
 # Change log
 
 See the [Change log](./CHANGELOG.md) for more information about the different versions, changes, etc.
@@ -127,6 +128,7 @@ 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
+refreshClient|undefined|Async callback to run when the session token is expired
 
 ```js
 const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
@@ -219,6 +221,19 @@ await client.logon();
 await client.logoff();
 ```
 
+## refreshClient callback
+The refreshClient is an async callback function with the SDK client as parameter, it is called when the ACC session is expired.
+The callback must refresh the client session and return it. if a SOAP query fails with session expiration error then it will be retried when the callback is defined.
+
+```js
+const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
+                                    url, "admin", "admin",
+                                    { refreshClient: async (client) => {
+                                        await client.logon();
+                                        return client;
+                                    }});
+```
+
 ## IP Whitelisting
 
 Campaign includes an IP whitelisting component which prevents connections from unauthorized IP addresses. This is a common source of authentication errors. 
@@ -456,7 +471,12 @@ More dynamic conversions can be achieved using the `as` function. See the types
 
 ```js
 stringValue = XtkCaster.as(anyValue, 6);
-````
+```
+
+In addition, the following helpers are available
+* `XtkCaster.isTimeType` to test if a data type is a date, time or timestamp
+* `XtkCaster.isStringType` to test if a data type is a string type (string, memo, etc.)
+* `XtkCaster.isNumericType` to test if a data type is a numeric type
 
 
 ## DOM helpers
@@ -999,6 +1019,8 @@ It's common to use variables in query conditions. For instance, in the above exa
 To prevent xtk ingestions vulnerabilities, you should not concatenate strings and write code such as expr: "@name = '" + name + "'": if the value of the name 
 parameter contains single quotes, your code will not work, but could also cause vulnerabilities.
 
+### sdk.escapeXtk
+
 The `sdk.escapeXtk` can be used to properly escape string litterals in xtk expressions. The function will also surround the escaped value with single quotes.
 
 You can use string concatenation like this. Note the lack of single quotes around the value.
@@ -1025,6 +1047,35 @@ This can also be used to escape other data types such as timestamps
 will return `{ expr: "@lastModified > = #2021-07-07T10:03:33.332Z# }`
 
 
+### sdk.escapeForLike
+
+This function escapes values so that they can be used in SQL or XTK like conditions. For example a search term "term" can be escaped as follows to implement a search conditions
+
+```
+    expr: `Lower([${xpath}]) LIKE '%${sdk.escapeForLike(term)}%'`,
+```
+
+### sdk.expandXPath & sdk.unexpandXPath
+
+In Campaign, xpaths are used to access attributes of entities. When XPaths are used in XTK expressions, there can be ambiguities, for instance, in the expression "country/@name", is "country/@name" a xpath or are we dividing the variable country by the value of the attribute @name?
+
+Amibiguity can be resolved by "expanding" the xpath from "country/@name" to "[country/@name]". The square brackets indicate an xpath.
+
+```
+    const expandedXPath = sdk.expandXPath(xpath);
+    const unexpandedXPath = sdk.unexpandXPath(expandedXPath);
+```
+
+### xtkConstText
+
+This function allows to convert literal values to xtk text constants, providing correct serialization. For instance, text constants will be quoted with single quotes, timestamps with the "#" character, etc.
+
+```
+    expect(sdk.xtkConstText("Hello", "string")).toBe("'Hello'");
+    expect(sdk.xtkConstText(-42.3, "double")).toBe("-42.3");
+    expect(sdk.xtkConstText("2022-02-15T09:49:04.000Z", "datetime")).toBe("#2022-02-15T09:49:04.000Z#");
+```
+
 
 ## Pagination
 Results can be retrieved in different pages, using the `@lineCount` and `@startLine` attributes. For instance, retrieves profiles 3 and 4 (skip 1 and 2)
@@ -1285,23 +1336,23 @@ The `application` object can be obtained from a client, and will mimmic the Camp
 
 | Attribute/Method | Description |
 |---|---|
-| buildNumber | The server build number
-| instanceName | The name of the Campaign instance
-| operator | Information about the current operator (i.e. logged user), of class `CurrentLogin`
-| packages | List of installed packages, as an array of strings
-| getSchema(schemaId) | Get a schema by id (see the Schemas section below)
-| hasPackage(name) | Tests if a package is installed or not
+| **buildNumber** | The server build number
+| **instanceName** | The name of the Campaign instance
+| **operator** | Information about the current operator (i.e. logged user), of class `CurrentLogin`
+| **packages** | List of installed packages, as an array of strings
+| **getSchema**(schemaId) | Get a schema by id (see the Schemas section below)
+| **hasPackage**(name) | Tests if a package is installed or not
 
 
 The `CurrentLogin` object has the following attributes / functions
 
 | Attribute/Method | Description |
 |---|---|
-| id | the internal id (int32) of the operator
-| login | the login name of the operator
-| computeString | A human readable name for the operator
-| timezone | The timezone of the operator
-| rights | An array of strings describing the rights of the operators
+| **id** | the internal id (int32) of the operator
+| **login** | the login name of the operator
+| **computeString** | A human readable name for the operator
+| **timezone** | The timezone of the operator
+| **rights** | An array of strings describing the rights of the operators
 
 # Schemas
 
@@ -1354,73 +1405,129 @@ const schema = application.getSchema("nms:recipient");
 This return a schema object of class `XtkSchema`
 
 
-### XtkSchema / XtkSchemaNode
-
-| Attribute/Method | | Description |
-|---|---|---|
-| schema | | The schema to which this node belongs
-| id | schema | For schemas, the id of the schema. For instance "nms:recipient"
-| namespace | schema | For schemas, the namespace of the schema. For instance "nms"
-| name |  | The name of the node (internal name)
-| label | | The label (i.e. human readable, localised) name of the node.
-| labelSingular | schema | The singular label (i.e. human readable, localised) name of the schema. The label of a schema is typically a plural.
-| description | | A long, human readable, description of the node
-| img | | The name of the image (if any) corresponding to the node
-| type | | The data type of the node, for instance "string", "long", etc.
-| length | | For string nodes, the maximum length of the node value
-| ref | |
-| isAttribute | | Indicates if the node is an attribute (true) or an element (false)
-| children | | A map of children of the node, indexed by name. Names never contain the "@" sign, even attribute names
-| childrenCount | | Number of children nodes
-| parent | | The parent node. Will be null for schema nodes
-| isRoot | | Indicates if the node is the root node of a schema, i.e. the first child of the schema node, whose name matches the schema name
-| userDescription | |
-| keys | | A map of keys in this node, indexed by key name. Map values are of type `XtkSchemaKey`
-| nodePath  | | The absolute full path of the node
-| hasChild(name) | | Tests if the node has a child wih the given name
-| findNode(path) | Find a child node using a xpath
-| isLibrary | schema | For schemas, indicates if the schema is a library
-| mappingType | schema | Schema mapping type. Usually "sql"
-| xml | schema | The XML (DOM) corresponding to this schema
-| root | schema | The schema root node, if there is one. A reference to a `XtkSchemaNode`
-| enumerations | schema | Map of enumerations in this schema, indexed by enumeration name. Values are of type `XtkEnumeration`
+### XtkSchema 
+
+| Attribute | Description |
+|---|---|
+| **id** | The id of the schema. For instance "nms:recipient"
+| **namespace** | The namespace of the schema. For instance "nms"
+| **name** | The name of the schema (internal name)
+| **label** | The label (i.e. human readable, localised) name of the node.
+| **labelSingular** | The singular label (i.e. human readable, localised) name of the schema. The label of a schema is typically a plural.
+| **isLibrary** | For schemas, indicates if the schema is a library
+| **mappingType** |Schema mapping type. Usually "sql"
+| **md5** | The MD5 code of the schema in the form of a hexadecimal string
+| **xml** | The XML (DOM) corresponding to this schema.<br>Note: this attribute is not available in the JS SDK.
+| **root** | The schema root node, if there is one. A reference to a `XtkSchemaNode`
+| **enumerations** | Map of enumerations in this schema, indexed by enumeration name. Values are of type `XtkEnumeration`
+| **userDescription** | The description of the schema in the form of a string.
+
+A schema is also a `XtkSchemaNode` and the corresponding properties/methods are also availale.
+
+### XtkSchemaNode
+
+| Attribute | | Description |
+|---|---|
+| **children** | A map of children of the node, indexed by name. Names never contain the "@" sign, even attribute names
+| **dataPolicy** | Returns a string of characters which provides the data policy of the current node.
+| **description** | A long, human readable, description of the node
+| **editType** |Returns a string of characters which specifies the editing type of the current node.
+| **enum** | The name of the enumeration for the node, or an empty string if the node does node have an enumeration. See `enumeration()` method to get the corresponding `XtkSchemaNode`
+| **enumerationImage** | Returns the name of the image of the current node in the form of a string of characters.
+| **folderModel** |Only on the root node, returns a string which contains the folder template(s). On the other nodes, it returns undefined.
+| **image**  | Returns the name of the image in the form of a string of characters.
+| **img** | Returns the name of the image in the form of a string of characters. (alias to `image` property)
+| **integrity** | Returns the link integrity type.
+| **keys** | A map of keys in this node, indexed by key name. Map values are of type `XtkSchemaKey`
+| **hasEnumeration** | Returns a boolean which indicates whether the value of the current node is linked to an enumeration.
+| **childrenCount** | Number of children nodes
+| **hasSQLTable** | Returns a boolean which indicates whether the current node is linked to an SQL table.
+| **hasUserEnumeration** | Returns a boolean which indicates whether the value of the current node is linked to a user enumeration.
+| **schema** | The schema to which this node belongs
+| **isAdvanced** | Returns a boolean which indicates whether the current node is advanced or not.
+| **isAnyType** | Returns a boolean which indicates whether the current node is ordinary.
+| **isAttribute** | Indicates if the node is an attribute (true) or an element (false)
+| **isAutoIncrement** | Returns a boolean which indicates whether the value of the current node is incremented automatically.
+| **isAutoPK** | Returns a boolean which indicates whether the current node is a primary key.
+| **isAutoUUID** | Yes | No | Returns a boolean which indicates whether the current node is an automatic UUID
+| **isAutoStg** | Yes | No | Returns a boolean which indicates whether the schema is a staging schema
+| **isBlob** | Returns a boolean which indicates whether the current node is a BLOB.
+| **isCalculated** | Returns a boolean which indicates whether the value of the current node is the result of a calculation. Note that compute strings are not considered as calculated attributes.
+| **isCDATA** | Returns a boolean which indicates whether the current node is mapped from CDATA type XML.
+| **isCollection** | Returns a boolean which indicates whether the current node is a collection of sub-elements and/or attributes. This is an alias to `unbound` and `isUnbound` properties.
+| **isDefaultOnDuplicate** | Returns a boolean. If the value added is vrai, during record deduplication, the default value (defined in defaultValue) is automatically reapplied during recording.
+| **isElementOnly** | Returns a boolean which indicates whether the current node is a logical sub-division of the schema.
+| **isExternalJoin** | True if the node is a link and if the join is external.
+| **isLink** | Returns a boolean which indicates whether the node is a link.
+| **isMappedAsXML** | Returns a boolean which indicates whether the node is an XML mapping.
+| **isMemo** | Returns a boolean which indicates whether the current node is mapped by a Memo.
+| **isMemoData** | Returns a boolean which indicates whether the current node is mapped by a MemoData.
+| **isNotNull** | Returns a boolean which indicates whether or not the current node can take the null value into account.
+| **isRequired** | Returns a boolean which indicates whether or not the value of the current node is mandatory.
+| **isRoot** | Indicates if the node is the root node of a schema, i.e. the first child of the schema node, whose name matches the schema name
+| **isSQL** | Returns a boolean which indicates whether the current node is mapped in SQL.
+| **isTemporaryTable** | Returns a boolean indicating whether the table is a temporary table. The table will not be created during database creation.| id | schema | For schemas, the id of the schema. For instance "nms:recipient"
+| **unbound** | Returns a boolean which indicates whether the current node has an unlimited number of children of the same type.
+| **joins** | Element of type "link" has an array of XtkJoin. See `joinNodes` method.
+| **label** | The label (i.e. human readable, localised) name of the node.
+| **name** | The name of the node (internal name)
+| **nodePath** | The absolute full path of the node
+| **parent** | The parent node. Will be null for schema nodes
+| **PKSequence** | Returns a character string that provides the name of the sequence to use for the primary key.
+| **packageStatus** | Returns a number that gives the package status.
+| **packageStatusString** |  Returns a string that gives the package status ("never", "always", "default", or "preCreate").
+| **revLink** | Returns the name of the reverse link in the link target schema. See `reverseLink` method to get the actual reverse link object
+| **SQLName** | The SQL name of the field. The property is an empty string if the object isn't an SQL type field.
+| **SQLTable** | The SQL name of the table. The property is an empty string if the object isn't the main element or if schema mapping isn't of SQL type.
+| **size** | For string nodes, the maximum length of the node value. Alias to `length`.
+| **length** | For string nodes, the maximum length of the node value
+| **target** | A string corresponding to the target of a link. Note that in the SDK, this is a string, whereas in the JS API, this is the actual target node. Because the SDK is async. Use `linkTarget` to get the target node of a link.
+| **type** | The data type of the node, for instance "string", "long", etc.
+| **userEnumeration** | Returns a string of characters which is the name of the user enumeration used by the current node.
+| **ref** | Some nodes are only references to other nodes. There are 2 kind of references. Local references are simply a xpath in the current schema (starting from the schema itself, and not the schema root). Fully qualified references are prefixed with a schema id. The target node can be accessed with the `refTarget` funtion.
+| **isMappedAsXml** | Is the field mapped as XML?
+
+| Method | Description |
+|---|---|
+| **hasChild**(name) | | Tests if the node has a child wih the given name
+| **findNode**(path) | Find a child node using a xpath
 
 
 ### XtkSchemaKey
 
 | Attribute/Method | Description |
 |---|---|
-| schema | The schema to which this key belongs
-| name |  The name of the key (internal name)
-| label | The label (i.e. human readable, localised) name of the key
-| description | A long, human readable, description of the key
-| isInternal |
-| allowEmptyPart |
-| fields | A map of key fields making up the key. Each value is a reference to a `XtkSchemaNode` 
+| **schema** | The schema to which this key belongs
+| **name** |  The name of the key (internal name)
+| **label** | The label (i.e. human readable, localised) name of the key
+| **description** | A long, human readable, description of the key
+| **isInternal** | Indicates if the key is an internal key (as opposed to an external key)
+| **allowEmptyPart** |
+| **fields** | A map of key fields making up the key. Each value is a reference to a `XtkSchemaNode` 
 
 ### XtkEnumeration
 
 | Attribute/Method | Description |
 |---|---|
-| name |  The name of the key (internal name)
-| label | The label (i.e. human readable, localised) name of the key
-| description | A long, human readable, description of the key
-| baseType | 
-| default |
-| hasImage |
-| values | A map of enumeration values, by name of value. Value is of type `XtkEnumerationValue`
+| **name** |  The name of the enumeration, fully qualified, i.e. prefixed with the schema id
+| **label** | The label (i.e. human readable, localised) name of the key
+| **description** | A long, human readable, description of the key
+| **baseType** | The base type of the enumeration, usually "string" or "byte"
+| **default** | The default value of the enumeration, casted to the enumeration type
+| **hasImage** | If the enumeration has an image
+| **values** | A map of enumeration values, by name of value. Value is of type `XtkEnumerationValue`
 
 ### XtkEnumerationValue
 
 | Attribute/Method | Description |
 |---|---|
-| name |  The name of the key (internal name)
-| label | The label (i.e. human readable, localised) name of the key
-| description | A long, human readable, description of the key
-| image |
-| enabledIf |
-| applicableIf |
-| value | The value of the enumeration (casted to the proper Javascript type)
+| **name** |  The name of the key (internal name)
+| **label** | The label (i.e. human readable, localised) name of the key
+| **description** | A long, human readable, description of the key
+| **image** |
+| **enabledIf** |
+| **applicableIf** |
+| **value** | The value of the enumeration (casted to the proper Javascript type)
 
 # Advanced Topics
 
@@ -1440,6 +1547,28 @@ If you need to access entity attributes (or child elements) in a generic way, yo
 * `getChildElements` to get the child elements. The result can be iterated on with a `for...of...` loop
 * `getElement` to get a child element whose attributes and child elements can also be accessed by the EntityAccessor API
 
+## Invoking SOAP calls dynamically
+Soap calls can be invoked dynamically as follows
+
+```js
+  const namespace = client.NLWS["xtkSession"];
+  const method = namespace["getOption"];
+  const result = await method.call(namespace, parameters);
+```
+
+where parameters is the list of parameters to the SOAP call.
+Parameters can be a function which can compute and return the list of parameters as the function is being called:
+
+```js
+  const result = await method.call(namespace, (method, callContext) => {
+    return parameters;
+  });
+```
+The `method` parameter is the XML definition of the SOAP method call. The `callContext` is an object which contains the following attributes:
+* `schemaId` is the id of the schema containing the SOAP method
+* `namespace` is the call namespace
+* `object` is only used for non-static call and contains the "this" of the call.
+
 
 
 # Build & Run

package/compile.js

@@ -38,6 +38,7 @@ var resources = [
     { name: "./optionCache.js" },
     { name: "./soap.js" },
     { name: "./crypto.js" },
+    { name: "./testUtil.js" },
     { name: "./application.js" },
     { name: "./client.js" },
     { name: "./index.js" },