@aitmed/cadl

README English

CADL class and utilities

This package contains the CADL class used to process CADL objects in addition to utility functions used to validate the CADL YAML files.

To build the validation UI run the following:

//to install the dependencies
    npm i

//to build the bundle.js in the public directory
    npm run build

To run the CADL validation UI locally run the following command

    npm run start:val_ui

then navigate to http://localhost:5000/

Expect the following errors if a CADL Object is invalid

-InvalidDestination -when page jump destination is not a valid page -UnableToRetrieveYAML -when something goes wrong in retrieving the yaml file form S3 -UnableToParseYAML -if there is a parsing error

To run the CADL test page UI locally run the following command

    npm run start:test

To update the @aitmed/cadl package run

    git checkout master
    git pull origin master

    npm run publish:public

MAIN CADL/NOODL Documentation

CADL - Lvl 2.5 SDK.

This layer is connected to Lvl 2 SDK and noodl-ui-dom. The primary function of CADL is to parse and translate a noodl yaml file. CADL can resolve references in noodl file by replacing short-handed variables (marked by ., .., etc.) with values. It will then go through noodl file, parse it, and replace any functions with Lvl 2 API commands as appropriate.

CADL is created in the frontend web layer. On creation, its constructor will be provided with aspectRatio, cadlVersion, and configUrl as parameters. CADL will have access to a store, which is created using provided parameters of env and configUrl. This store will have access to Lvl 2 SDK, and implements Lvl 2 SDK's setters and getters. Inside of CADL constructor, several properties of store will be redirected, and store's noodlInstance will refer to the CADL.

An integral part of CADL is the root. When CADL is created, initRoot() function is called, and two things are attached to the empty root: an empty actions {} object, and an object of builtIn functions, which include things like createNewAccount, signIn, uploadDocument, etc. This process is completed within the CADL layer.

Implementation of CADL relies on a few important functions, which are supported by an array of helper functions. The important ones are:

CADL.init()

This function is called to initialize the CADL. This function can take three parameters (BaseDataModel, BaseCSS, and BasePage), but generally none are provided. A config variable is declared and assigned the variable retrieved from Lvl 2 SDK using loadConfig(), and config is destructured and assigned to the proper variables in CADL. From config, cadlBaseUrl is retrieved, and is used to locate cadlEndpointUrl. Using the cadlEndpointUrl we get cadlEndpoint, which contains baseUrl, assetsUrl, and preload. These are vital assets for parsing the noodl file.

The variable preload can be destructured to receive BasePage, BaseCSS, and BaseDataModel. These are the base elements in a noodl file; there are separate 'pages' in noodl that needs processing as well, such as SignIn, SignUp, and DocumentDetails, but these three serve as the base for other pages. For each of these pages, they are first retrieved using this.getPage() method, then processed down using this.processPopulate() method, and finally set into state using this.newDispatch() method. The key here is the processPopulate() method, which translates variables that start with ['.', '..', '=', '~'] into their fully expanded values using a recurssive algorithm. Once this process completes, these fully parsed objects/functions/variables are updated into root through state control dispatches.

After the above steps are completed, init() function checks for any items stored in local storage 'Global', and repeats the above parsing process. This process is not detected when the web first renders.

CADL.initPage()

This is another important method of CADL. Once the app starts, each page in noodl will need to be rendered separately, and that is the primary function of initPage(). This function is called in frontend code in src/index.js, and by createPreparePage() function. This function takes three parameters: pageName, an empty array denoted skip, and options. pageName variable is self-explanatory; skip[] can be used to include properties that are not to be "processed," e.g [edge] will lead to teh edge property of the noodl file to not be processed and will retain all variable references '..,.,=...etc'; the most notable thing about options is that once destructured, it contains a variable called evolve, and that must be true in order for the page to be rendered, otherwise the page will return. The evolve variable is invoked in frontend code, builtIn functions goto and goBack.

After the processing and evaluating are finished, initPage() then proceeds to process noodl page in a fashion similar to init(), using processPopulate(), but also dispatch method.

CADL.processPopulate()

This function is the primary function that handles the resolution of noodl files by processing references of variables in noodl files and replacing them with their fully extended form. This is specifically being done with the populateKeys() method, which recursively goes through the noodl file, find any symbols that signifies a referencing variable, and replace that variable with its fully extended form.

The function takes in five parameters: source, lookFor, skip, pageName, withFns. -source: the source page of noodl, written in object format -lookFor: an array of symbols to look out for, these symbols denote variables at current directory, parent directory, etc. that must be identified and have related variables resolved -skip: items to skip while parsing through source file -withFns: a boolean true or false that denotes whether or not to populate the functions -pageName: name of the noodl page

CADL.dispatch

This function handles the updating of the state(i.e noodl.root) as a result of return values from apis or builtIn fns.This function is bounded to the noodl/cadl instance and called within the builtIn fns and the object services (document, edges, vertexes). Within this function you will see the logic for 'eval-object.'

CADL.newDispatch

This is a lower level dispatch function that gets called to directly affect the state of the noodl.root through SET_VALUE, DELETE_VALUE, SET_ROOT_PROPERTIES, SET_LOCAL_PROPERTIES.

Methods That Can Be Accessed Through CADL/NOODL:

These functions can be accessed through builtInFns, which are attached to root as root.builtIn

Method	Returns	Description
builtInFns.string
.formatUnixtime_en(unixTime: number)	string	Returns a date-time string associated with the given number.
.formatUnixtimeLT_en(unixTime: number)	string	Return a time string associated with the given number.
.formatDurationInSecond(unixTime: number)	string	Returns the amount of time that has elapsed since Dec 31, 1969, 4:00 PM as a string
.concat(stringArr: string[])	string	Concatenate an array of strings into one string, and returns the string
.equal({ string1, string2 })	boolean	Compare the two input strings and returns true if they are equal, otherwise returns false
.getFirstChar(string: string)	string	Returns the first character of the string in upperCase
.retainNumber({value:any})	number	Parses the value into a number
builtInFns.object
.remove({ object, key })	void	Creates a deep clone of the object, and removes the value in the deep clone at location specified by key
.set({ object: Record<string,any>, key: string, value: any })	void	Creates a deep clone of the object, and updates the deep clone at location specified by key with value
.has({ object: Record<string,any>, key: string })	boolean	Checks if input object contains a value at specified key
.clear({object:Record<string,any>, key:string})	void	Clears the value of the object at the given key e.g sets value at key to ''
.get({object:Record<string,any>, key:string})	any	Returns the value of the object at the given key
.clearAndSetKey({ object, item, key, value })	void	Clears one key of all items of an object, and sets one item e.g used for list radio
builtInFns.array
.add({ object, value })	void	Adds value to the provided array(object)
.addByIndex({object, value, index})	void	Adds value to the provided array(object) at the given index
.SortBy({ object, iterate, orders })	array	Sorts array applying the iterate function and orders is by desc or asc
.clear({object})	void	Clears all values in given array
.removeByKey({ object, key })	void	Removes the item in array if item has key
.removeByName({ object, key, name })	void	Removes the item in array if item.key matches name
.removeByValue({object, value})	void	Removes the item from the array that matches value
.removeById({object, id})	void	Removes the item from the array that matches the id
.removeByindex({object, index})	void	Removes the item from the array at the given index
.removeWeekByIndexs({object1, object2, index, duration})	void	TODO
.append({ newMessage, messages })	void	Appends given newMessage to messages array
.has({ object, value })	boolean	Returns whether or not the value is in the array
.hasKey({ object, key })	boolean	Returns whether ot not the array has a value witht the given key
.AddWeek({ object, duration, index, key })	void	TODO
.push({ newMessage, messages })	void	Pushes newMessage to messages array
.covertToJsonArray({ array })	object	Converts items in array to key:value objects
.getListLength({ object })	number	Returns the length of the array
.copyByKey({ array1, array2, key })	array	Copies items from array1 to array2 if key matches
.changeColorByKey({ array, key, value })	void	TODO
builtInFns.number
.inRange({ number, start, end })	boolean	Returns true or false depending if the given number is in range of start and end
.multiply({ number, multiple })	number	Returns the product of number and multiple
builtInFns.eccNaCl
.signature(message: string)	string	Uses level2SDK.utilServices.signature to encrypt the input string and generate an encrypted signature
.verifySignature(signature: string, pkSign: string)	boolean	Uses level2SDK.utilServices.verifySignature to verify if the signature is valid
.decryptAES({ key, message })	string	??? Decrypts message with the provided key through level2SDK.utilServices.sKeyDecrypt
.skCheck({ pk, sk })	boolean	Uses level2SDK.utilServices.aKeyCheck to check if the provided secret key is valid
.generateESAK({ pk: string })	string	Generates a symmetric key through level2SDK.utilServices.generateSKey and encrypts the key with level2SDK.utilServices.aKeyEncrypt
.decryptESAK({ esak: Uint8Array | string, publicKey: string, secretKey: string })	string	Decrypt the encrypted session access key with public key and secret key
.isEdgeEncrypted({ id: string })	boolean	Asynchronous function. Checks if an edge is encrypted, i.e. it has a besak or eesak
.getSAKFromEdge({ id: string })	string	Asynchronous function. Retrieves the edge by id, decrypts its attached besak or eesak, and returns it if exists, otherwise returns an empty string
.encryptData({ esak: Uint8Array | string, publicKey: string, data: Uint8Array })	Uint8Array	Encrypts data with esak and returns encrypted data in Uint8Array format
.decryptData({ esak: Uint8Array | string, publicKey: string, secretKey: string, data: Uint8Array })	Uint8Array	Decrypts the esak with provided public key and secret key
builtInFns.ecos
.shareDoc({ sourceDoc, targetEdgeID })	object	Share a document with a target edge by making a copy of the document as a Note object, then creating a new Document and pass in targetEdgeID as the document's edge_id
.shareDocList({ sourceDocList, targetEdgeID })	void	Shares multiple documents at a time using similar logic as shareDoc
Access directly from builtInFns
.createNewAccount({ name })	object	Asynchronous function. Name is destructured to include phoneNumber, password, and userName. These credentials will be verified, and the function then calls Account.create. Account.create data will be returned.
.signIn({ phoneNumber, password, verificationCode })	object	Asynchronous function. Calls Account.login to complete login procedure. Account.login's returned data will be returned.
.loginByPassword(password)	None	Asynchronous function. Calls Account.loginByPassword
.storeCredentials({ pk, sk, esk, userId })	None	Stores provided credentials in local storage
.SignInOk()	boolean	Calls Account.getStatus
.uploadDocument({ title, tags = [], content, type, dataType = 0 })	<Record<string, any>>	Calls Document.create and returns the response

Account Services

Method	Returns	Description
.requestVerificationCode(phone_number)	object	Asynchronous function. Calls store.level2SDK.Account.requestVerificationCode and returns the response
.create(phone_number, password, verification_code, userName)	object	Asynchronous function. Calls store.level2SDK.Account.createInvitedUser or store.level2SDK.Account. createUser depending on statusCode. Returns a userVertex object.
.login(phone_number, password, verification_code)	object	Asynchronous function. Calls loginByVerificationCode and loginByPassword. Returns a user or userVertex object
.loginByVerificationCode(phone_number, verification_code)	object	Asynchronous function. Calls store.level2SDK.Account.loginNewDevice. Returns a Status
.loginByPassword(password)	object	Asynchronous function. Calls store.level2SDK.Account.login, then retrieves userVertex using user.id. Returns userVertex object
.updatePassword(old_password, new_password)	None	Asynchronous function. Updates user password by calling store.level2SDK.Account.changePasswordWithOldPassword
.updatePasswordByVerificationCode(phone_number, verification_code, new_password)	None	Asynchronous function. Updates user password by calling store.level2SDK.Account.changePasswordWithVerificationCode
.verifyUserPassword(password: string)	boolean	Uses store.level2SDK.Account.verifyUserPassword to verify the password
.updateProfile(profile: AccountTypes.Profile)	AccountTypes.User	Updates the profile by deleting old one and creating a new profile
.retrieve()	AccountTypes.User	Retrieves the user using information nested in the root

Document Services

Method	Returns	Description
.create({ edge_id, title, tags = [], content, type, mediaType, dataType = 0, dTypeProps })	Note	Asynchronous function. Creates an encrypted document, attaches it to an edge, and returns the document in Note format. Utilizes functions in store.level2SDK.utilServices
.retrieve(id, _edge)	Note	Asynchronous function. Retrieves the document specified by id and returns the returned document as a Note object
.update(id, { edge_id, title, content, mediaType, tags, type, dTypeProps })	Note	Asynchronous function. Updates the document specified by id and returns the updated document as a Note object

Note Services

Note is analogous to Document. Any Note related functions are legacy code, with the exception of documentToNote, which is under src/services/Note/utils

Method	Returns	Description
.documentToNote(document, _edge, esakOfCurrentUser)	Note	Asynchronous function. Generally, only document is needed for input parameter. This function normalizes the data after it retrieves the document from the server, and turns the ECOS document to a readable note/document

---

Function: init Location: src/CADL/CADL.ts

throw new UnableToLoadConfig(
  `An error occured while trying to load the config. ` +
    `Config settings: ${JSON.stringify({
      apiHost: store.apiHost,
      apiProtocol: store.level2SDK.apiProtocol,
      apiVersion: store.level2SDK.apiVersion,
      configUrl: store.configUrl,
      env: store.env,
    })}`,
  err,
)

Function: builtIn Location: src/CADL/services/builtIn.ts

console.error(`Error occurred while invoking a builtIn function`, {
  apiObject,
  error: err,
  inputArgs: input,
  path: pathArr,
  pageName,
})

Function: sendRetrieveDocument Location: src/CADL/services/documents.ts

console.error(`Error occurred in the function "sendRetrieveDocument"`, {
  apiObject,
  cacheIndex,
  error,
  pageName,
  requestOptions,
})

throw error

Function: sendCreateDocument Location: src/CADL/services/documents.ts

console.error(`Error occurred in the function "sendCreateDocument"`, {
  apiObject,
  cacheIndex,
  error,
  pageName,
  requestOptions,
})
throw error

Function: sendCreateDocument Location: src/CADL/services/documents.ts

console.error(`Error occurred running the function Document.create`, {
  apiObject,
  data: populatedCurrentVal,
  error,
  pageName,
})
throw err

throw new UnableToLocateValue(
  `Missing reference ${targetEdgeID} in function "shareDocList"`,
)

console.error(`Error occurred in function "sendRetrieveEdge"`, {
  apiObject,
  cacheIndex,
  error: err,
  idList,
  requestOptions,
})

console.error(`Error occurred in function "sendCreateEdge"`, {
  apiObject,
  error: err,
  pageName,
  someObjectInTheFunction: obj,
})