DDO.js library docs (#1509)

* Add publishing flow seq diagram. Create validate README for ddo.js.

* Update validate code snippet.

* Add instantiating a ddo with ddo.js lib.

* Update docs. Created retrieve-fields.md README.

* Created edit-fields guide for ddo.js.

* Updated SUMMARY and installation step for ddo.js.

* Fix typo.

* Fix review. Created dedicated section for publishing flow.

* Update SUMMARY.

* Update vars.

Author: mariacarmina

.gitbook/assets/cli/DDO-Publishing-Flow.png

@@ -0,0 +1,80 @@
+@startuml "DDO Publishing Flow"
+title "DDO Publishing Flow"
+
+skinparam sequenceArrowThickness 2
+skinparam roundcorner 10
+skinparam maxmessagesize 85
+skinparam sequenceParticipant underline
+
+actor "End User" as end_user
+participant "Consumer\n(Ocean CLI)" as consumer
+participant "Ocean.js" as ocean_js
+participant "Ocean Node" as ocean_node
+database "Ocean Node's Database\n(Typesense/ElasticSearch)" as db
+participant "Smart Contracts" as smart_contracts
+participant "DDO.js" as ddo_js
+
+group Asset Creation
+end_user -> consumer: Requests to publish a dataset with selected file.
+note over end_user
+Command: **npm run publish <ddo file>**
+end note
+consumer -> ocean_js: Calls asset creation function
+group DataNFT, Datatoken and Pricing Schema Deployment
+ocean_js -> smart_contracts: Deploy data NFT & datatoken with pricing schema
+note over smart_contracts
+    Pricing schemas are:
+    - dispenser
+    - fixed rate exchange.
+end note
+smart_contracts --> smart_contracts: Events emmitted
+ocean_js -> smart_contracts: Retrieve **NFTCreated** and **DatatokenCreated** events
+alt Datatoken is **not** template 4 for EVM credentials
+    ocean_js -> ocean_node: Requests encryption for DDO services files
+    alt Encryption is successful
+        ocean_node --> ocean_js: Returns **200 OK** response
+    else Encryption is **NOT** successful
+        ocean_node --> ocean_js: Returns error status code
+    end
+else Datatoken is template 4 for EVM credentials
+    note over ocean_js
+    No encryption for service files needed,
+    because on Oasis the datatoken, which contains
+    the services, is deployed encrypted form.
+    end note
+end
+end group
+group DDO Encryption
+ocean_js -> ocean_node: Requests encryption for DDO object
+alt Encryption is successful
+        ocean_node --> ocean_js: Returns **200 OK** response
+    else Encryption is **NOT** successful
+        ocean_node --> ocean_js: Returns error status code
+    end
+end group
+group DDO Validation
+ocean_js -> ocean_node: Requests validation for DDO structure
+ocean_node -> ddo_js: Validate DDO structure
+ddo_js -> ddo_js: Use SHACL schemas depending on DDO version for validation
+alt Validation is successful
+        ddo_js --> ocean_node: Response with success
+        ocean_node --> ocean_js: Returns **200 OK** response
+        ocean_js -> smart_contracts: Calls **setMetadata** on chain
+        ocean_js --> consumer: Returns DID
+        consumer --> end_user: Returns DID
+        group Ocean Node indexes new DDOs
+            smart_contracts --> smart_contracts: Emit event **MetadataCreated**
+            ocean_node -> smart_contracts: Listens to **MetadataCreated** events
+            ocean_node -> ocean_node: Indexes DDO from chain in processMetadataEvent
+            ocean_node -> db: Stores DDO in the database
+            db --> ocean_node
+        end group
+
+    else Validation is **NOT** successful
+        ddo_js --> ocean_node: Response with error and log the message
+        ocean_node --> ocean_js: Returns error status code
+    end
+
+end group
+end group
+@enduml

.gitbook/assets/cli/flow.puml

@@ -0,0 +1,39 @@
+
+@startuml "DDO Validation Flow using DDO.js Library"
+title "DDO Publishing Flow using DDO.js Library"
+
+skinparam sequenceArrowThickness 2
+skinparam roundcorner 10
+skinparam maxmessagesize 85
+skinparam sequenceParticipant underline
+
+participant "Ocean.js" as ocean_js
+participant "Ocean Node" as ocean_node
+database "Ocean Node's Database\n(Typesense/ElasticSearch)" as db
+participant "Smart Contracts" as smart_contracts
+participant "DDO.js" as ddo_js
+
+group DDO Validation
+ocean_js -> ocean_node: Requests validation for DDO structure
+ocean_node -> ddo_js: Validate DDO structure
+ddo_js -> ddo_js: Use SHACL schemas depending on DDO version for validation
+alt Validation is successful
+        ddo_js --> ocean_node: Response with success
+        ocean_node --> ocean_js: Returns **200 OK** response
+        ocean_js -> smart_contracts: Calls **setMetadata** on chain
+        ocean_js --> ocean_js: Returns DID
+        group Ocean Node indexes new DDOs
+            smart_contracts --> smart_contracts: Emit event **MetadataCreated**
+            ocean_node -> smart_contracts: Listens to **MetadataCreated** events
+            ocean_node -> ocean_node: Indexes DDO from chain in processMetadataEvent
+            ocean_node -> db: Stores DDO in the database
+            db --> ocean_node
+        end group
+    else Validation is **NOT** successful
+        ddo_js --> ocean_node: Response with error and log the message
+        ocean_node --> ocean_js: Returns error status code
+    end
+
+end group
+
+@enduml

.gitbook/assets/ddo.js/validate-flow.puml

@@ -34,12 +34,14 @@
     * [Roles](developers/contracts/roles.md)
     * [Pricing Schemas](developers/contracts/pricing-schemas.md)
     * [Fees](developers/contracts/fees.md)
+  * [Publish Flow Overview](developers/publishing-flow-architecture.md)
   * [Revenue](developers/contracts/revenue.md)
   * [Fractional Ownership](developers/fractional-ownership.md)
   * [Community Monetization](developers/community-monetization.md)
   * [Metadata](developers/metadata.md)
   * [Identifiers (DIDs)](developers/identifiers.md)
-  * [DDO Specification](developers/ddo-specification.md)
+  * [New DDO Specification](developers/new-ddo-specification.md)
+  * [Obsolete DDO Specification](developers/ddo-specification.md)
   * [Storage Specifications](developers/storage.md)
   * [Fine-Grained Permissions](developers/fg-permissions.md)
   * [Retrieve datatoken/data NFT addresses & Chain ID](developers/retrieve-datatoken-address.md)
@@ -61,6 +63,12 @@
     * [Edit](developers/ocean-cli/edit.md)
     * [Consume](developers/ocean-cli/consume.md)
     * [Run C2D Jobs](developers/ocean-cli/run-c2d.md)
+  * [DDO.js](developers/ddo.js/README.md)
+    * [Instantiate a DDO](developers/ddo.js/instantiate-ddo.md)
+    * [DDO Fields interactions](developers/ddo.js/retrieve-fields.md)
+    * [Validate](developers/ddo.js/validate.md)
+    * [Edit DDO Fields](developers/ddo.js/edit-fields.md)
+  * [Compute to data](developers/compute-to-data/README.md)
   * [Compute to data](developers/compute-to-data/README.md)
     * [Architecture](developers/compute-to-data/compute-to-data-architecture.md)
     * [Datasets & Algorithms](developers/compute-to-data/compute-to-data-datasets-algorithms.md)

.gitbook/assets/ddo.js/validation-flow.png

@@ -0,0 +1,27 @@
+---
+description: >-
+  Ocean Protocol's JavaScript library to manipulate with DDO and Asset fields and to validate DDO structures depending on version.
+---
+
+# DDO.js
+
+Welcome to the DDO.js! Your utility library for working with DDOs and Assets like a pro. 🚀
+
+The DDO.js offers a wide range of functionalities, enabling you to:
+
+* [**Instantiate DDO**](instantiate-ddo.md) 📤 by `DDOManager` depending on version.
+* [**Retrieve**](retrieve-fields.md) 📥 DDO data together with Asset fields using defined helper methods.
+* [**Validate DDO**](validate.md) 📤 using SHACL schemas.
+* [**Edit**](edit-fields.md) ✏️ existing fields of DDO and Asset.
+
+## Installation
+
+It is available as `npm` package, therefore to install in your `js` project, simply run in the console:
+
+```bash
+npm install @oceanprotocol/ddo-js
+```
+
+## Key Information
+
+Let's dive into the DDO.js's capabilities together! If you're ready to explore each functionality in detail, simply go through the next pages.

SUMMARY.md

@@ -0,0 +1,41 @@
+# Edit DDO Fields ✏️
+
+To edit fields in the DDO structure, DDO instance from `DDOManager` is required to call `updateFields` method which is present for all types of DDOs, but targets specific DDO fields, according to DDO's version.
+
+**NOTE**: There are some restrictions that need to be taken care of before updating fields which do not exist for certain DDO.
+
+For e.g. `deprecatedDDO`, the update on `services` key is not supported, because a `deprecatedDDO` is not supposed to store `services` information. It is design to support only: `id`, `nftAddress`, `chainId`, `indexedMetadata.nft.state`.
+
+Supported fields to be updated are:
+
+```javascript
+
+export interface UpdateFields {
+  id?: string;
+  nftAddress?: string;
+  chainId?: number;
+  datatokens?: AssetDatatoken[];
+  indexedMetadata?: IndexedMetadata;
+  services?: ServiceV4[] | ServiceV5[];
+  issuer?: string;
+  proof?: Proof;
+}
+```
+
+## Usage of Update Fields Function
+
+Now let's use [DDO V4 example](./instantiate-ddo.md#usage-examples), `DDOExampleV4` into the following javascript code, assuming `@oceanprotocol/ddo-js` has been installed as dependency before:
+
+```javascript
+const { DDOManager } = require ('@oceanprotocol/ddo-js');
+
+const ddoInstance = DDOManager.getDDOClass(DDOExampleV4);
+const nftAddressToUpdate = "0xfF4AE9869Cafb5Ff725f962F3Bbc22Fb303A8aD8"
+ddoInstance.updateFields({ nftAddress: nftAddressToUpdate }) // It supports update on multiple fields
+// The same script can be applied on DDO V5 and deprecated DDO from `Instantiate DDO section`.
+```
+**Execute script**
+
+```bash
+node update-ddo-fields.js
+```