From b9dfdc51186ed6bd38a18cf94ac5aea0f09279a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20Guti=C3=A9rrez?= Date: Wed, 9 Jan 2019 15:43:33 +0100 Subject: [PATCH 1/4] included external typings #79 --- package-lock.json | 8 ++++++++ package.json | 1 + tsconfig.json | 5 ++++- 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/package-lock.json b/package-lock.json index defb7a3..ec66f96 100644 --- a/package-lock.json +++ b/package-lock.json @@ -211,6 +211,14 @@ "resolved": "https://registry.npmjs.org/@types/node/-/node-10.12.18.tgz", "integrity": "sha512-fh+pAqt4xRzPfqA6eh3Z2y6fyZavRIumvjhaCL753+TVkGKGhpPeyrJG2JftD0T9q4GF00KjefsQ+PQNDdWQaQ==" }, + "@types/node-fetch": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/@types/node-fetch/-/node-fetch-2.1.4.tgz", + "integrity": "sha512-tR1ekaXUGpmzOcDXWU9BW73YfA2/VW1DF1FH+wlJ82BbCSnWTbdX+JkqWQXWKIGsFPnPsYadbXfNgz28g+ccWg==", + "requires": { + "@types/node": "*" + } + }, "@types/shelljs": { "version": "0.8.1", "resolved": "https://registry.npmjs.org/@types/shelljs/-/shelljs-0.8.1.tgz", diff --git a/package.json b/package.json index bc013c2..042a4ab 100644 --- a/package.json +++ b/package.json @@ -55,6 +55,7 @@ "dependencies": { "@oceanprotocol/keeper-contracts": "^0.5.3", "@oceanprotocol/secret-store-client": "~0.0.14", + "@types/node-fetch": "^2.1.4", "bignumber.js": "^8.0.1", "ethereumjs-util": "^6.0.0", "node-fetch": "^2.3.0", diff --git a/tsconfig.json b/tsconfig.json index 111e8db..2c76110 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -14,7 +14,10 @@ "preserveConstEnums": true, "outDir": "./dist/node/", "rootDir": "./src/", - "sourceMap": true + "sourceMap": true, + "typeRoots": [ + "node_modules/@types" + ] }, "include": [ "src/**/*" From b2d2271e50f896ffc056ea753ae991614f4c4729 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20Guti=C3=A9rrez?= Date: Wed, 9 Jan 2019 16:08:08 +0100 Subject: [PATCH 2/4] added comment documentation on DDO related classes #79 --- src/ddo/AdditionalInformation.ts | 25 +++++- src/ddo/Curation.ts | 23 +++++- src/ddo/DDO.ts | 38 +++++++-- src/ddo/MetaData.ts | 9 +-- src/ddo/MetaDataBase.ts | 135 ++++++++++++++++++++++++++++--- 5 files changed, 206 insertions(+), 24 deletions(-) diff --git a/src/ddo/AdditionalInformation.ts b/src/ddo/AdditionalInformation.ts index 54d2111..c4878eb 100644 --- a/src/ddo/AdditionalInformation.ts +++ b/src/ddo/AdditionalInformation.ts @@ -1,7 +1,24 @@ import StructuredMarkup from "./StructuredMarkup" +/** + * Additional Information of Assets Metadata. + * @see https://github.com/oceanprotocol/OEPs/tree/master/8#additional-information + */ export default class AdditionalInformation { + /** + * An indication of update latency - i.e. How often are updates expected (seldom, + * annually, quarterly, etc.), or is the resource static that is never expected + * to get updated. + * @type {string} + * @example "yearly" + */ public updateFrecuency: string = "yearly" + + /** + * A link to machine-readable structured markup (such as ttl/json-ld/rdf) + * describing the dataset. + * @type {StructuredMarkup[]} + */ public structuredMarkup: StructuredMarkup[] = [ { uri: "http://skos.um.es/unescothes/C01194/jsonld", @@ -10,7 +27,13 @@ export default class AdditionalInformation { { uri: "http://skos.um.es/unescothes/C01194/turtle", mediaType: "text/turtle", - }as StructuredMarkup, + } as StructuredMarkup, ] + + /** + * Checksum of attributes to be able to compare if there are changes in + * the asset that you are purchasing. + * @type {string} + */ public checksum: string } diff --git a/src/ddo/Curation.ts b/src/ddo/Curation.ts index bc40e86..95e0cc0 100644 --- a/src/ddo/Curation.ts +++ b/src/ddo/Curation.ts @@ -1,5 +1,26 @@ +/** + * Curation attributes of Assets Metadata. + * @see https://github.com/oceanprotocol/OEPs/tree/master/8#curation-attributes + */ export default class Curation { + /** + * Decimal value between 0 and 1. 0 is the default value. + * @type {number} + * @example 0.93 + */ public rating: number = 0.93 + + /** + * Number of votes. 0 is the default value. + * @type {number} + * @example 123 + */ public numVotes: number = 123 - public schema: string = "Binary Votting" + + /** + * Schema applied to calculate the rating. + * @type {number} + * @example "Binary Votting" + */ + public schema?: string = "Binary Votting" } diff --git a/src/ddo/DDO.ts b/src/ddo/DDO.ts index 49b447f..94825b1 100644 --- a/src/ddo/DDO.ts +++ b/src/ddo/DDO.ts @@ -2,12 +2,26 @@ import Authentication from "./Authentication" import PublicKey from "./PublicKey" import Service from "./Service" +/** + * DID Descriptor Object. + * Contains all the data related to an asset. + */ export default class DDO { + /** + * Serializes the DDO object. + * @param {DDO} DDO to be serialized. + * @return {string} DDO serialized. + */ public static serialize(ddo: DDO): string { return JSON.stringify(ddo, null, 2) } + /** + * Deserializes the DDO object. + * @param {DDO} DDO to be deserialized. + * @return {string} DDO deserialized. + */ public static deserialize(ddoString: string): DDO { const ddo = JSON.parse(ddoString) @@ -15,6 +29,10 @@ export default class DDO { } public "@context": string = "https://w3id.org/future-method/v1" + /** + * DID, descentralized ID. + * @type {string} + */ public id: string public publicKey: PublicKey[] public authentication: Authentication[] @@ -26,14 +44,18 @@ export default class DDO { authentication?: Authentication[], service?: Service[], }) { - this.authentication = ddo ? ddo.authentication ? ddo.authentication : [] : [] - this.id = ddo ? ddo.id ? ddo.id : null : null - this.publicKey = ddo ? ddo.publicKey ? ddo.publicKey : [] : [] - this.service = ddo ? ddo.service ? ddo.service : [] : [] + this.authentication = (ddo && ddo.authentication) || [] + this.id = (ddo && ddo.id) || null + this.publicKey = (ddo && ddo.publicKey) || [] + this.service = (ddo && ddo.service) || [] } + /** + * Finds a service of a DDO by ID. + * @param {string} serviceDefinitionId Service ID. + * @return {Service} Service. + */ public findServiceById(serviceDefinitionId: string): Service { - if (!serviceDefinitionId) { throw new Error("serviceDefinitionId not set") } @@ -43,8 +65,12 @@ export default class DDO { return service } + /** + * Finds a service of a DDO by type. + * @param {string} serviceType Service type. + * @return {Service} Service. + */ public findServiceByType(serviceType: string): Service { - if (!serviceType) { throw new Error("serviceType not set") } diff --git a/src/ddo/MetaData.ts b/src/ddo/MetaData.ts index 1a5c01a..5d89388 100644 --- a/src/ddo/MetaData.ts +++ b/src/ddo/MetaData.ts @@ -58,11 +58,8 @@ export default class MetaData { public curation: Curation constructor(metaData?: MetaData) { - this.additionalInformation = metaData ? - metaData.additionalInformation ? metaData.additionalInformation : - additionalInformation : additionalInformation - this.base = metaData ? metaData.base ? metaData.base : base : base - this.curation = metaData ? metaData.curation ? metaData.curation : curation : curation + this.additionalInformation = (metaData && metaData.additionalInformation) || additionalInformation + this.base = (metaData && metaData.base) || base + this.curation = (metaData && metaData.curation) || curation } - } diff --git a/src/ddo/MetaDataBase.ts b/src/ddo/MetaDataBase.ts index 1c5d98f..a20aad6 100644 --- a/src/ddo/MetaDataBase.ts +++ b/src/ddo/MetaDataBase.ts @@ -1,21 +1,116 @@ +/** + * Base attributes of Assets Metadata. + * @see https://github.com/oceanprotocol/OEPs/tree/master/8#base-attributes + */ export default class MetaDataBase { + + /** + * Descriptive name of the Asset. + * @type {string} + * @example "UK Weather information 2011" + */ public name: string = "UK Weather information 2011" - public type: string = "dataset" - public description: string = "Weather information of UK including temperature and humidity" - public size: string = "3.1gb" + + /** + * Type of the Asset. Helps to filter by the type of asset, + * initially ("dataset", "algorithm", "container", "workflow", "other"). + * @type {string} + * @example "dataset" + */ + public type: "dataset" | "algorithm" | "container" | "workflow" | "other" = "dataset" + + /** + * Details of what the resource is. For a dataset, this attribute + * explains what the data represents and what it can be used for. + * @type {string} + * @example "Weather information of UK including temperature and humidity" + */ + public description?: string = "Weather information of UK including temperature and humidity" + + /** + * The date on which the asset was created or was added. + * @type {string} + * @example "2012-10-10T17:00:000Z" + */ public dateCreated: string = "2012-10-10T17:00:000Z" + + /** + * Size of the asset (e.g. 18MB). In the absence of a unit (MB, kB etc.), kB will be assumed. + * @type {string} + * @example "3.1gb" + */ + public size: string = "3.1gb" + + /** + * Name of the entity generating this data (e.g. Tfl, Disney Corp, etc.). + * @type {string} + * @example "Met Office" + */ public author: string = "Met Office" + + /** + * Short name referencing the license of the asset (e.g. Public Domain, CC-0, CC-BY, No License Specified, etc. ). + * If it's not specified, the following value will be added: "No License Specified". + * @type {string} + * @example "CC-BY" + */ public license: string = "CC-BY" - public copyrightHolder: string = "Met Office" - public encoding: string = "UTF-8" - public compression: string = "zip" + + /** + * The party holding the legal copyright. Empty by default. + * @type {string} + * @example "Met Office" + */ + public copyrightHolder?: string = "Met Office" + + /** + * File encoding. + * @type {string} + * @example "UTF-8" + */ + public encoding?: string = "UTF-8" + + /** + * File compression (e.g. no, gzip, bzip2, etc). + * @type {string} + * @example "zip" + */ + public compression?: string = "zip" + + /** + * File format, if applicable. + * @type {string} + * @example "text/csv" + */ public contentType: string = "text/csv" - public workExample: string = "423432fsd,51.509865,-0.118092,2011-01-01T10:55:11+00:00,7.2,68" + + /** + * Example of the concept of this asset. This example is part + * of the metadata, not an external link. + * @type {string} + * @example "423432fsd,51.509865,-0.118092,2011-01-01T10:55:11+00:00,7.2,68" + */ + public workExample?: string = "423432fsd,51.509865,-0.118092,2011-01-01T10:55:11+00:00,7.2,68" + + /** + * List of content URLs resolving the Asset files. + * @type {string | string[]} + * @example "https://testocnfiles.blob.core.windows.net/testfiles/testzkp.zip" + */ public contentUrls: string | string[] = [ "https://testocnfiles.blob.core.windows.net/testfiles/testzkp.zip", "https://testocnfiles.blob.core.windows.net/testfiles/testzkp.zip", ] - public links: any[] = [ + + /** + * Mapping of links for data samples, or links to find out more information. + * Links may be to either a URL or another Asset. We expect marketplaces to + * converge on agreements of typical formats for linked data: The Ocean Protocol + * itself does not mandate any specific formats as these requirements are likely + * to be domain-specific. + * @type {any[]} + */ + public links?: any[] = [ { sample1: "http://data.ceda.ac.uk/badc/ukcp09/data/gridded-land-obs/gridded-land-obs-daily/", }, @@ -26,7 +121,27 @@ export default class MetaDataBase { fieldsDescription: "http://data.ceda.ac.uk/badc/ukcp09/", }, ] - public inLanguage: string = "en" - public tags: string = "weather, uk, 2011, temperature, humidity" + + /** + * The language of the content. Please use one of the language + * codes from the {@link https://tools.ietf.org/html/bcp47 IETF BCP 47 standard}. + * @type {String} + * @example "en" + */ + public inLanguage?: string = "en" + + /** + * Keywords or tags used to describe this content. Multiple entries in a keyword + * list are typically delimited by commas. Empty by default. + * @type {String} + * @example "weather, uk, 2011, temperature, humidity" + */ + public tags?: string = "weather, uk, 2011, temperature, humidity" + + /** + * Price of the asset. + * @type {String} + * @example 10 + */ public price: number = 10 } From 4074d95f1e39045ea753aabf8c41236427f663d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20Guti=C3=A9rrez?= Date: Wed, 9 Jan 2019 16:15:32 +0100 Subject: [PATCH 3/4] added comments on some internal classes #79 --- src/ConfigProvider.ts | 14 +++++++- src/aquarius/Aquarius.ts | 29 ++++++++++++++--- src/aquarius/AquariusProvider.ts | 17 ++++++++-- src/brizo/Brizo.ts | 5 ++- src/brizo/BrizoProvider.ts | 17 ++++++++-- src/keeper/Keeper.ts | 55 +++++++++++++++++++++++++++++++- src/keeper/Web3Provider.ts | 10 +++++- src/utils/WebServiceConnector.ts | 13 +++++--- 8 files changed, 142 insertions(+), 18 deletions(-) diff --git a/src/ConfigProvider.ts b/src/ConfigProvider.ts index d133fc8..34242ee 100644 --- a/src/ConfigProvider.ts +++ b/src/ConfigProvider.ts @@ -1,15 +1,27 @@ import Config from "./models/Config" +/** + * Stores the configuration of the library. + */ export default class ConfigProvider { + /** + * @return {Config} Library config. + */ public static getConfig(): Config { return ConfigProvider.config } + /** + * @param {Config} Library config. + */ public static setConfig(config: Config) { - ConfigProvider.config = config } + /** + * Library config. + * @type {Config} + */ private static config: Config } diff --git a/src/aquarius/Aquarius.ts b/src/aquarius/Aquarius.ts index fba0110..abe61cb 100644 --- a/src/aquarius/Aquarius.ts +++ b/src/aquarius/Aquarius.ts @@ -8,17 +8,18 @@ import SearchQuery from "./query/SearchQuery" const apiPath = "/api/v1/aquarius/assets/ddo" +/** + * Provides a interface with Aquarius. + * Aquarius provides an off-chain database store for metadata about data assets. + */ export default class Aquarius { - private url: string constructor(config: Config) { - this.url = config.aquariusUri } public async getAccessUrl(accessToken: any, payload: any): Promise { - const accessUrl: string = await WebServiceConnectorProvider.getConnector() .post(`${accessToken.service_endpoint}/${accessToken.resource_id}`, payload) .then((response: any): string => { @@ -40,8 +41,12 @@ export default class Aquarius { return accessUrl } + /** + * Search over the DDOs using a query. + * @param {SearchQuery} query Query to filter the DDOs. + * @return {Promise} + */ public async queryMetadata(query: SearchQuery): Promise { - const result: DDO[] = await WebServiceConnectorProvider.getConnector() .post(`${this.url}${apiPath}/query`, JSON.stringify(query)) .then((response: any) => { @@ -64,8 +69,12 @@ export default class Aquarius { return result } + /** + * Search over the DDOs using a query. + * @param {SearchQuery} query Query to filter the DDOs. + * @return {Promise} + */ public async queryMetadataByText(query: SearchQuery): Promise { - const fullUrl = new URL(`${this.url}${apiPath}/query`) fullUrl.searchParams.append("text", query.text) fullUrl.searchParams.append("sort", decodeURIComponent(JSON.stringify(query.sort))) @@ -93,6 +102,11 @@ export default class Aquarius { return result } + /** + * Stores a DDO in Aquarius. + * @param {DDO} ddo DDO to be stored. + * @return {Promise} Final DDO. + */ public async storeDDO(ddo: DDO): Promise { const fullUrl = `${this.url}${apiPath}` const result: DDO = await WebServiceConnectorProvider.getConnector() @@ -115,6 +129,11 @@ export default class Aquarius { return result } + /** + * Retrieves a DDO by DID. + * @param {DID} did DID of the asset. + * @return {Promise} DDO of the asset. + */ public async retrieveDDO(did: DID): Promise { const fullUrl = `${this.url}${apiPath}/${did.getDid()}` const result = await WebServiceConnectorProvider.getConnector() diff --git a/src/aquarius/AquariusProvider.ts b/src/aquarius/AquariusProvider.ts index e881643..3422aa7 100644 --- a/src/aquarius/AquariusProvider.ts +++ b/src/aquarius/AquariusProvider.ts @@ -1,20 +1,33 @@ import ConfigProvider from "../ConfigProvider" import Aquarius from "./Aquarius" +/** + * Provides the Aquarius instance. + */ export default class AquariusProvider { + /** + * Set an Aquarius instance. + * @param {Aquarius} aquarius New Aquarius instance. + */ public static setAquarius(aquarius: Aquarius) { - AquariusProvider.aquarius = aquarius } + /** + * Returns Acuarius instance. It creates a new one if it's not defined. + * @returns {Aquarius} Aquarius instance. + */ public static getAquarius() { - if (!AquariusProvider.aquarius) { AquariusProvider.aquarius = new Aquarius(ConfigProvider.getConfig()) } return AquariusProvider.aquarius } + /** + * Aquarius instance. + * @type {Aquarius} + */ private static aquarius: Aquarius = null } diff --git a/src/brizo/Brizo.ts b/src/brizo/Brizo.ts index 900225c..58c97f1 100644 --- a/src/brizo/Brizo.ts +++ b/src/brizo/Brizo.ts @@ -3,11 +3,14 @@ import WebServiceConnectorProvider from "../utils/WebServiceConnectorProvider" const apiPath = "/api/v1/brizo/services" +/** + * Provides a interface with Brizo. + * Brizo is the technical component executed by the Publishers allowing to them to provide extended data services. + */ export default class Brizo { private url: string constructor(config: Config) { - this.url = config.brizoUri } diff --git a/src/brizo/BrizoProvider.ts b/src/brizo/BrizoProvider.ts index f8e5c3d..1584e70 100644 --- a/src/brizo/BrizoProvider.ts +++ b/src/brizo/BrizoProvider.ts @@ -1,20 +1,33 @@ import ConfigProvider from "../ConfigProvider" import Brizo from "./Brizo" +/** + * Provides the Brizo instance. + */ export default class BrizoProvider { + /** + * Set an Brizo instance. + * @param {Brizo} brizo New Brizo instance. + */ public static setBrizo(brizo: Brizo) { - BrizoProvider.brizo = brizo } + /** + * Returns Acuarius instance. It creates a new one if it's not defined. + * @returns {Brizo} brizo instance. + */ public static getBrizo() { - if (!BrizoProvider.brizo) { BrizoProvider.brizo = new Brizo(ConfigProvider.getConfig()) } return BrizoProvider.brizo } + /** + * Brizo instance. + * @type {Brizo} + */ private static brizo: Brizo = null } diff --git a/src/keeper/Keeper.ts b/src/keeper/Keeper.ts index 6c66ac2..a8f4fad 100644 --- a/src/keeper/Keeper.ts +++ b/src/keeper/Keeper.ts @@ -8,9 +8,20 @@ import OceanToken from "./contracts/Token" import Web3Provider from "./Web3Provider" +/** + * Interface with Ocean Keeper contracts. + * Ocean Keeper implementation where we put the following modules together: + * - TCRs: users create challenges and resolve them through voting to maintain registries. + * - Ocean Tokens: the intrinsic tokens circulated inside Ocean network, which is used in the voting of TCRs. + * - Marketplace: the core marketplace where people can transact with each other with Ocean tokens. + */ export default class Keeper { - public static async getInstance() { + /** + * Returns Keeper instance. + * @return {Promise} + */ + public static async getInstance(): Promise { if (Keeper.instance === null) { Keeper.instance = new Keeper() @@ -26,16 +37,58 @@ export default class Keeper { return Keeper.instance } + /** + * Keeper instance. + * @type {Keeper} + */ private static instance: Keeper = null + /** + * Ocean Token smart contract instance. + * @type {OceanToken} + */ public token: OceanToken + + /** + * Ocean Market smart contract instance. + * @type {OceanMarket} + */ public market: OceanMarket + + /** + * Ocean Auth smart contract instance. + * @type {OceanAuth} + */ public auth: OceanAuth + + /** + * Service agreement smart contract instance. + * @type {ServiceAgreement} + */ public serviceAgreement: ServiceAgreement + + /** + * Access conditions smart contract instance. + * @type {AccessConditions} + */ public accessConditions: AccessConditions + + /** + * Payment conditions smart contract instance. + * @type {PaymentConditions} + */ public paymentConditions: PaymentConditions + + /** + * DID registry smart contract instance. + * @type {DIDRegistry} + */ public didRegistry: DIDRegistry + /** + * Returns the network by name. + * @return {Promise} Network name. + */ public async getNetworkName(): Promise { return Web3Provider.getWeb3().eth.net.getId() .then((networkId) => { diff --git a/src/keeper/Web3Provider.ts b/src/keeper/Web3Provider.ts index 5f92759..be0472c 100644 --- a/src/keeper/Web3Provider.ts +++ b/src/keeper/Web3Provider.ts @@ -3,7 +3,11 @@ import ConfigProvider from "../ConfigProvider" export default class Web3Provider { - public static getWeb3() { + /** + * Returns Web3 instance. + * @return {Web3} + */ + public static getWeb3(): Web3 { if (Web3Provider.web3 === null) { const config = ConfigProvider.getConfig() const web3Provider = config.web3Provider || new Web3.providers.HttpProvider(config.nodeUri) @@ -12,5 +16,9 @@ export default class Web3Provider { return Web3Provider.web3 } + /** + * Web3 instance. + * @type {Web3} + */ private static web3: Web3 = null } diff --git a/src/utils/WebServiceConnector.ts b/src/utils/WebServiceConnector.ts index 3e1b5d2..8449e17 100644 --- a/src/utils/WebServiceConnector.ts +++ b/src/utils/WebServiceConnector.ts @@ -1,8 +1,11 @@ -import fetch from "node-fetch" +import fetch, { Response, RequestInit, BodyInit } from "node-fetch" +/** + * Provides a common interface to web services. + */ export default class WebServiceConnector { - public async post(url, payload): Promise { + public async post(url: string, payload: BodyInit): Promise { return this.fetch(url, { method: "POST", body: payload, @@ -12,7 +15,7 @@ export default class WebServiceConnector { }) } - public async get(url): Promise { + public async get(url: string): Promise { return this.fetch(url, { method: "GET", headers: { @@ -21,7 +24,7 @@ export default class WebServiceConnector { }) } - public async put(url, payload): Promise { + public async put(url: string, payload: BodyInit): Promise { return this.fetch(url, { method: "PUT", body: payload, @@ -31,7 +34,7 @@ export default class WebServiceConnector { }) } - private async fetch(url, opts): Promise { + private async fetch(url: string, opts: RequestInit): Promise { return fetch(url, opts) } } From 89dbc1053246ca1d61e7773c837cd4c6feaaa88b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pedro=20Guti=C3=A9rrez?= Date: Wed, 9 Jan 2019 16:17:23 +0100 Subject: [PATCH 4/4] added comments to main Ocean class #79 --- src/ocean/Account.ts | 24 ++++++++++++++ src/ocean/DID.ts | 25 ++++++++++++++- src/ocean/Ocean.ts | 74 +++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 118 insertions(+), 5 deletions(-) diff --git a/src/ocean/Account.ts b/src/ocean/Account.ts index f85dcf1..4a44188 100644 --- a/src/ocean/Account.ts +++ b/src/ocean/Account.ts @@ -5,13 +5,24 @@ import Web3Provider from "../keeper/Web3Provider" import Balance from "../models/Balance" import OceanBase from "./OceanBase" +/** + * Account information. + */ export default class Account extends OceanBase { private balance: Balance + /** + * Balance of Ocean Token. + * @return {Promise} + */ public async getOceanBalance(): Promise { return (await Keeper.getInstance()).token.balanceOf(this.id) } + /** + * Balance of Ether. + * @return {Promise} + */ public async getEtherBalance(): Promise { // Logger.log("getting balance for", account); return Web3Provider @@ -24,6 +35,10 @@ export default class Account extends OceanBase { }) } + /** + * Balances of Ether and Ocean Token. + * @return {Promise} + */ public async getBalance(): Promise { if (!this.balance) { @@ -36,6 +51,11 @@ export default class Account extends OceanBase { return this.balance } + /** + * Request Ocean Tokens. + * @param {number} amount Tokens to be requested. + * @return {Promise} + */ public async requestTokens(amount: number): Promise { await (await Keeper.getInstance()) .market @@ -43,6 +63,10 @@ export default class Account extends OceanBase { return amount } + /** + * Returns the account public key. + * @return {Promise} + */ public async getPublicKey(): Promise { const web3 = Web3Provider.getWeb3() diff --git a/src/ocean/DID.ts b/src/ocean/DID.ts index 608ec37..ef3d13f 100644 --- a/src/ocean/DID.ts +++ b/src/ocean/DID.ts @@ -2,8 +2,16 @@ import IdGenerator from "./IdGenerator" const prefix = "did:op:" +/** + * Decentralized ID. + */ export default class DID { + /** + * Parses a DID from a string. + * @param {string} didString DID in string. + * @return {DID} + */ public static parse(didString: string): DID { let did: DID if (didString.startsWith(prefix)) { @@ -20,21 +28,36 @@ export default class DID { return did } + /** + * Returns a new DID. + * @return {DID} + */ public static generate(): DID { return new DID(IdGenerator.generateId()) } + /** + * ID. + * @type {string} + */ private id: string private constructor(id: string) { - this.id = id } + /** + * Returns the DID. + * @return {string} + */ public getDid(): string { return `${prefix}${this.id}` } + /** + * Returns the ID. + * @return {string} + */ public getId(): string { return this.id } diff --git a/src/ocean/Ocean.ts b/src/ocean/Ocean.ts index 841ab18..9141bc6 100644 --- a/src/ocean/Ocean.ts +++ b/src/ocean/Ocean.ts @@ -27,10 +27,17 @@ import Access from "./ServiceAgreements/Templates/Access" import EventListener from "../keeper/EventListener" +/** + * Main interface for Ocean Protocol. + */ export default class Ocean { - public static async getInstance(config: Config) { - + /** + * Returns the instance of Ocean. + * @param {Config} config Ocean instance configuration. + * @return {Promise} + */ + public static async getInstance(config: Config): Promise { if (!Ocean.instance) { ConfigProvider.setConfig(config) Ocean.instance = new Ocean() @@ -40,13 +47,25 @@ export default class Ocean { return Ocean.instance } - private static instance = null + /** + * Ocean instance. + * @type {Ocean} + */ + private static instance: Ocean = null + /** + * Keeper instance. + * @type {Keeper} + */ private keeper: Keeper private constructor() { } + /** + * Returns the list of accounts. + * @return {Promise} + */ public async getAccounts(): Promise { // retrieve eth accounts @@ -55,12 +74,22 @@ export default class Ocean { return ethAccounts.map((address: string) => new Account(address)) } + /** + * Returns a DDO by DID. + * @param {string} did Decentralized ID. + * @return {Promise} + */ public async resolveDID(did: string): Promise { - const d: DID = DID.parse(did) return AquariusProvider.getAquarius().retrieveDDO(d) } + /** + * Registers a new DDO. + * @param {MetaData} metadata DDO metadata. + * @param {Account} publisher Publicher account. + * @return {Promise} + */ public async registerAsset(metadata: MetaData, publisher: Account): Promise { const {didRegistry} = this.keeper @@ -153,6 +182,13 @@ export default class Ocean { return storedDdo } + /** + * Signs a service agreement by DID. + * @param {string} did Decentralized ID. + * @param {string} serviceDefinitionId Service definition ID. + * @param {Account} consumer Consumer account. + * @return {Promise} + */ public async signServiceAgreement(did: string, serviceDefinitionId: string, consumer: Account): Promise { @@ -201,6 +237,15 @@ export default class Ocean { } } + /** + * Creates a new service agreement. + * @param {string} did Decentralized ID. + * @param {string} serviceDefinitionId Service definition ID. + * @param {string} serviceAgreementId Service agreement ID. + * @param {string} serviceAgreementSignature Service agreement signature. + * @param {Function} cb Callback executen when the access is granted. + * @param {Account} consumer Consumer account. + */ public async initializeServiceAgreement(did: string, serviceDefinitionId: string, serviceAgreementId: string, @@ -247,6 +292,16 @@ export default class Ocean { consumer.getId()) } + /** + * Executes a service agreement. + * @param {string} did Decentralized ID. + * @param {string} serviceDefinitionId Service definition ID. + * @param {string} serviceAgreementId Service agreement ID. + * @param {string} serviceAgreementSignature Service agreement signature. + * @param {Account} consumer Consumer account. + * @param {Account} publisher Publisher account. + * @return {Promise} + */ public async executeServiceAgreement(did: string, serviceDefinitionId: string, serviceAgreementId: string, @@ -270,10 +325,21 @@ export default class Ocean { return serviceAgreement } + /** + * Search over the assets using a query. + * @param {SearchQuery} query Query to filter the assets. + * @return {Promise} + */ public async searchAssets(query: SearchQuery): Promise { return AquariusProvider.getAquarius().queryMetadata(query) } + + /** + * Search over the assets using a keyword. + * @param {SearchQuery} text Text to filter the assets. + * @return {Promise} + */ public async searchAssetsByText(text: string): Promise { return AquariusProvider.getAquarius().queryMetadataByText({ text,