Completed doc - making it v0.1.0

Author: perki

AppTemplates.md

@@ -0,0 +1,144 @@
+This document is part of [Generic toolkit for server and web applications](README.md).
+
+# APPLICATION TEMPLATES
+
+
+App templates based on HDS Model, provide frameworks to build applications for HDS.
+
+- **AppManagingAccount**: App which manages Collectors. A "Collector" handles a "Request" and set of "Responses". => With access to some HDS data from other accounts.
+- **AppClientAccount**: Handles requests from `AppManagingAccount` and corresponding responses (agree, refuse, revoke).
+
+## Application class
+Both templates extend `Application` class 
+
+An application is based on 
+- one `connection`: an instance of `pryv.Connection`
+- one `baseStreamId`: the streamId where the application will store its own operation data (i.e. state management) - This stream should be a children of stream `applications`.
+- one `appName`
+
+### instantiating an Application 
+Either use: 
+- `App{ExtensionName}.newFromApiEndpoint(baseStreamId, apiEndpoint, appName)`
+- `App{ExtensionName}.newFromConnection(baseStreamId, connection, appName)`
+
+It will return an instance already initialized with eventual necessary streams created. 
+
+### extending Application class
+Check the code for mode details. 
+
+## AppManagingAccount
+
+### instantiating
+Either use: 
+- `AppManagingAccount.newFromApiEndpoint(baseStreamId, apiEndpoint, appName)`
+- `AppManagingAccount.newFromConnection(baseStreamId, connection, appName)`
+
+Params:
+- **apiEndpoint or connection** must have `master` or `personnal` access rights.
+
+### appManagingAccount.getCollectors();
+Get current `Collector` instances related to this app
+
+### appManagingAccount.getCollectorById();
+Get one `Collector`from its id.
+
+### appManagingAccount.createCollector(name)
+Create new `Collector`
+
+
+### AppManagingAccount Collectors class
+A collector is holding 
+- A single request for accessing a set of streams 
+- A set of `CollectorInvite` which are to be submitted to **clients**
+
+It has 3 possible states `draft`=> `active` => `deactivated`
+
+Collector instances are created and managed by AppManagingAccount.
+
+#### collector.id
+You may use this as a reference to retrieve a specific collector from an app
+ 
+#### collector.statusCode
+One of 'draft', 'active', 'deactivated'
+
+#### collector.statusData
+Payload that can be modified
+
+#### async collector.save()
+After modifying `collector.statusData` you should save it.
+
+#### async collector.publish()
+Once the edition is done and saved, validate and publish. (Can be done just once);
+
+#### async collector.getInvites()
+List of current invites
+
+#### async collector.checkInbox ()
+Check if new 'accept', 'refuse', 'revoke' messages have been received.
+
+#### AppManagingAccount - CollectorInvite class
+A collector invite represents the state of a 1 - 1 relationship between a Collector => A User
+It's materialized by an `event` in one of the streams of the Collector
+
+`collectorInvite` instances are created and retrieved by `Collector` instances.
+
+##### collectorInvite.displayName()
+Returns the display name set at creation
+
+
+##### collectorInvite.getSharingData()
+When `pending` this will return an `apiEndpoint` and an `eventId` to be shared with a 3rd party app using `ApplicationClient`. This data will be consumed by `appclient.handleIncomingRequest(apiEndpoint, eventId)` to initiate the relationship.
+
+##### collectorInvite.status()
+Returns one of `pending`, `active`, `error`.
+
+In case of error, (meaning, means not accessible) the call `collectorInvite.errorType()` will return `revoked` or `refused`.
+
+##### collectorInvite.connection and collectorInvite.apiEndpoint
+As an invite is a 1 - 1 relationship, when active, it holds a connection to the matching account.
+
+#### collectorInvite.dateCreation()
+Returns a `Date`object.
+
+##### async collectorInvite.checkAndGetAccessInfo()
+Check if connection is valid. (only if active)
+If the result is "forbidden" update and set as revoked.
+
+Returns the `accessInfo` on success, which can be useful to get the hds username or other infos and the account.
+
+## AppClientAccount
+
+The counterpart of `AppManagingAccount` for "client" applications.
+
+### instantiating
+Either use: 
+- `AppClientAccount.newFromApiEndpoint(baseStreamId, apiEndpoint, appName)`
+- `AppClientAccount.newFromConnection(baseStreamId, connection, appName)`
+### appClientAccount.handleIncomingRequest(apiEndpoint, incomingEventId)
+To be called when the app receives a new request issued by `AppManagingAccount's collectorInvite.getSharingData()`. Returns a `CollectorClient` instance.
+
+### appClientAccount.getCollectorClients()
+Get current `CollectorClient` instances.
+
+### appClientAccount.getCollectorClientByKey(collectorKey)
+Get a specific `CollectorClient` instance.
+
+### CollectorClient class
+
+#### collectorClient.key
+Identifier to retrieve a collector from appClientAccount.
+
+#### collectorClient.status
+One of 'Incoming', 'Active', 'Deactivated', 'Refused'
+
+#### collectorClient.requestData
+The data holding the requestFrom the invite
+
+#### collectorClient.accept()
+Accept current request
+
+#### collectorClient.revoke()
+Revoke current request
+
+#### collectorClient.refuse()
+Refuse current request

README.md

@@ -161,7 +161,11 @@ const expected = [
 
 App templates based on HDS Model, provide frameworks to build applications for HDS.
 
-Some of the functionalities will be moved from the lib
+- **AppManagingAccount**: App which manages Collectors. A "Collector" handles a "Request" and set of "Responses". => With access to some HDS data from other accounts.
+- **AppClientAccount**: Handles requests from `AppManagingAccount` and corresponding responses (agree, refuse, revoke).
+
+Details and examples for theses App templates can be found in [AppTemplates.md]
+
 
 ### toolkit
 Misc. tools 
@@ -184,7 +188,18 @@ await connection.streamsAutoCreate.ensureExistsForItems(['body-weight', 'profile
 <head>
     <script src="../docs/hds-lib.js"></script>
     <script>
-      model = new HDSLib.HDSModel();
+      HDSLib.settings.setServiceInfoURL('https://demo.datasafe.dev/reg/service/info');
+      HDSLib.settings.setPreferredLocales(['fr', 'en']); // ordered
+
+      // init model in async code
+      (async () => {
+        await HDSLib.initHDSModel(); // need just one
+        // from now on an in all your code you use HDSLib.model 
+
+        // you may create new HDSService with:
+        const service = new HDSService();
+
+      })();
     </script>
 </head>
 ```

docs/hds-lib.js.map

@@ -20406,7 +20406,7 @@ class HDSModelAuthorizations {
    * /!\ Does not handle requests with streamId = "*"
    * @param {Array<itemKeys>} itemKeys
    * @param {Object} [options]
-   * @param {string} [options.defaultLevel] (default = write) one of 'read', 'write', 'contribute', 'writeOnly'
+   * @param {string} [options.defaultLevel] (default = write) one of 'read', 'manage', 'contribute', 'writeOnly'
    * @param {boolean} [options.includeDefaultName] (default = true) defaultNames are needed for permission requests but not for access creation
    * @param {Array<AuthorizationRequestItem>} [options.preRequest]
    * @return {Array<AuthorizationRequestItem>}
@@ -20955,6 +20955,7 @@ class AppClientAccount extends Application {
    * When the app receives a new request for data sharing
    * @param {string} apiEndpoint
    * @param {string} [incomingEventId] - Information for the recipient
+   * @returns {CollectorClient}
    */
   async handleIncomingRequest (apiEndpoint, incomingEventId) {
     // make sure that collectorClientsMap is initialized
@@ -21390,7 +21391,10 @@ class Collector {
     return this.streamId;
   }
 
-  /** @type {StatusData} */
+  /**
+   * @type {StatusData} 
+   * Payload that can be modified
+   * */
   get statusData () {
     if (this.#cache.status == null) throw new Error('Init Collector first');
     return this.#cache.status.content.data;
@@ -21841,7 +21845,8 @@ class CollectorClient {
   }
 
   /**
-   * Create a new Event
+   * @private
+   * used by appClientAccount.handleIncomingRequest
    */
   static async create (app, apiEndpoint, requesterEventId, accessInfo) {
     // check content of accessInfo
@@ -21867,6 +21872,7 @@ class CollectorClient {
   }
 
   /**
+   * @private
    * reset with new request Event of ApiEndpoint
    * Identical as create but keep current event
    */
@@ -22159,6 +22165,10 @@ class CollectorInvite {
     this.eventData = eventData;
   }
 
+  /**
+   * private
+   * @param {*} eventData 
+   */
   setEventData (eventData) {
     if (eventData.id !== this.eventData.id) throw new HDSLibError('CollectInvite event id does not match new Event');
     this.eventData = eventData;
@@ -23849,7 +23859,7 @@ describe('[LOCX] Localization', () => {
       assert.deepEqual(getPreferredLocales(), defaultLocales);
     });
 
-    it('[LOSE] setPreferredLocales throws error if language code unssuported', () => {
+    it('[LOSE] setPreferredLocales throws error if language code unsuported', () => {
       try {
         setPreferredLocales(['ex', 'en', 'fr', 'ut']);
         throw new Error('Should throw error');
@@ -24303,6 +24313,7 @@ __webpack_require__(/*! ./hdsModel.test */ "./tests/hdsModel.test.js");
 __webpack_require__(/*! ./libSettings.test */ "./tests/libSettings.test.js");
 __webpack_require__(/*! ./localizeText.test */ "./tests/localizeText.test.js");
 __webpack_require__(/*! ./toolkitStreamAutoCreate.test */ "./tests/toolkitStreamAutoCreate.test.js");
+
 })();
 
 /******/ })()

docs/tests-browser.js

@@ -1,6 +1,6 @@
 {
   "name": "hds-lib",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Health Data Safe - Library",
   "main": "src/index.js",
   "scripts": {

docs/tests-browser.js.map

@@ -27,6 +27,7 @@ class AppClientAccount extends Application {
    * When the app receives a new request for data sharing
    * @param {string} apiEndpoint
    * @param {string} [incomingEventId] - Information for the recipient
+   * @returns {CollectorClient}
    */
   async handleIncomingRequest (apiEndpoint, incomingEventId) {
     // make sure that collectorClientsMap is initialized

package.json

@@ -56,7 +56,10 @@ class Collector {
     return this.streamId;
   }
 
-  /** @type {StatusData} */
+  /**
+   * @type {StatusData}
+   * Payload that can be modified
+   * */
   get statusData () {
     if (this.#cache.status == null) throw new Error('Init Collector first');
     return this.#cache.status.content.data;

src/appTemplates/AppClientAccount.js

@@ -68,7 +68,8 @@ class CollectorClient {
   }
 
   /**
-   * Create a new Event
+   * @private
+   * used by appClientAccount.handleIncomingRequest
    */
   static async create (app, apiEndpoint, requesterEventId, accessInfo) {
     // check content of accessInfo
@@ -94,6 +95,7 @@ class CollectorClient {
   }
 
   /**
+   * @private
    * reset with new request Event of ApiEndpoint
    * Identical as create but keep current event
    */

src/appTemplates/Collector.js

@@ -86,6 +86,10 @@ class CollectorInvite {
     this.eventData = eventData;
   }
 
+  /**
+   * private
+   * @param {*} eventData
+   */
   setEventData (eventData) {
     if (eventData.id !== this.eventData.id) throw new HDSLibError('CollectInvite event id does not match new Event');
     this.eventData = eventData;